Author's Guide Introduction

Introduction
Creating a new document
Testing your document
Creating elements in your document
Modifying and deleting existing elements
Popup menus

IDE FPML Tutorial

Inserting special characters into your document
Using line breaks and page breaks
Creating and using styles
Using SPAN elements
Using DIV elements
Using TABLE elements
Using PAGEAREA elements
Using a PAGEBOX element
Updating the outermost DOCUMENT element
Using variables in documents
Using recordsets and drilldowns
Using conditional elements
Using loop elements
Using additional methods

Query Designer Tutorial

Introduction
The sample database
An initial example
A drilldown example

XML Data Tutorial

Introduction
The sample XML data files
The XMLTest example
Creating and modifying XMLDATA tags


FPWeb User Tutorial

Introduction
FPWeb Fundamentals
Queries and Fields
Record Filters


IDE Theme File

Introduction
Theme file definition

IDE XML Tags File

Introduction
XML Tags file definition


Introduction

Note: If you are interested in the FPWeb facility, which allows your customers and internal users to easily customize and generate documents from their web browsers, you can begin by referring to the section FPWeb User Tutorial within this guide.

The FinerEdge Publisher Integrated Development Environment (IDE) comes with every FinerEdge Publisher installation. The IDE manual fully describes the operation and all commands of the IDE, and is accessible anytime from within the IDE by either pressing the F1 key or pressing the "Help" button of any dialog. When either the F1 key or the "Help" button is pressed while a dialog is shown, the IDE manual is further positioned to the corresponding help information for that dialog. In addition, the IDE manual and the FinerEdge Publisher reference manual are both accessible from either the "Help" menu of the IDE or from the FinerEdge Publisher installed Windows menu.

To start the IDE, select the "FinerEdge Publisher" menu from the Windows Start menu. Then, select the "FinerEdge Publisher IDE" menu item within the "FinerEdge Publisher" menu. Note: If this is the first time that the IDE is started, the IDE preferences dialog will be shown. The default settings are applicable to a typical environment within the United States. However, if you wish to set up a environment for another country, we recommend that you examine and set the date format, date delimiter character, time format, time delimiter character, decimal point character, thousands character, currency character, and perhaps select the "Metric display" checkbox.

» Back to the Table of Contents. «

Creating a new document

After starting the FinerEdge Publisher IDE, you can create a new document by pressing the "Create a new document" button, which is the first button shown in the top buttonbar. In the dialog shown, select the option "Create a new document and main method" and press the OK button. (Choosing the option "Create a new document and database definition" will show the built-in FinerEdge Publisher Query Designer, which is discussed within this document under the topic "Query Designer Tutorial".)

The METHOD editor is then shown with the option "Main Method" already selected. Type "Test" into the field "Name" and press the "OK" button. A main method element is created for you and displayed in the visual designer view. We'll discuss how to create and use additional methods in more detail later in this document.

Note: For a detailed explanation on the various IDE views, please refer to the IDE manual.

» Back to the Table of Contents. «

Testing your document

Select the "end" method element by clicking your mouse on the second icon shown (the first icon is the "start" method element). Other than additional methods, all other elements must be inserted between (within) a method element pair. Next, type your name (you will observe the "end" method element moving down and your name will appear in its place).

Now, press the "Select document generation" button from the top buttonbar. The document will be generated and you'll see your name displayed within the document generation view. To return, press the "Select visual definition" button from the top buttonbar. This simple example illustrates how easy it is to create a FinerEdge Publisher document from within the IDE.

» Back to the Table of Contents. «

Creating elements in your document

A large number of the buttons on the IDE's left and bottom button bars represent element creation buttons. Element creation buttons will either immediately insert an element into the selected visual designer or markup editor view at the insertion/selection point, or bring up a corresponding element dialog where you can specify the element's attributes.

Alternatively, you can also click and drag a particular button from the left or bottom buttonbars onto the selected view. The new element is always inserted prior to the element where the drop occurs. Regardless of the technique used, after the attributes have been entered into the element's dialog and the OK button is pressed, the element is inserted into the selected visual designer or markup view.

» Back to the Table of Contents. «

Modifying and deleting existing elements

Updating or modifying existing elements from both the visual designer and markup views is easy with FinerEdge Publisher. Simply position your insertion/selection point on the element you're interested in by left-clicking your mouse at that location in the document. Then press the "Edit the current element" button. Alternatively, you can also double-click anywhere on the element. If a corresponding element dialog exists, it will subsequently be shown with all of the attributes and styles for the element filled into its fields.

Within element dialogs, many fields support additional assistance from other dialogs by showing a button to the right of the field. An often seen example in FinerEdge Publisher is a button displaying an ellipsis (i.e., "..."), which indicates that the field can be further formatted by pressing that button.

Deleting an element can be accomplished by selecting the element and pressing the "Delete" key on your keyboard or by pressing the "Delete the current element" button.

» Back to the Table of Contents. «

Popup menus

In both the FinerEdge Publisher visual designer and markup views, many of the commands can also be performed by right clicking your mouse over a particular element. A pop-up menu will be subsequently shown with applicable commands for the selected view and element.

» Back to the Table of Contents. «



Inserting special characters into your document

FinerEdge Publisher fully supports Unicode character sets. As such, any type of special characters can be easily inserted or modified in your document by using the "Insert/edit characters" button on the IDE's left button bar. Alternatively, you may also click your mouse on the text you'd like to edit and press the "Edit the current element" button or simply double-click on the desired text.

» Back to the Table of Contents. «

Using page breaks and line breaks

The page break element "PAGEBR" causes a conditional or unconditional logical page break to occur in the document. If a height attribute is given with the PAGEBR element, the specified height must remain on the page (with respect to an element's margins, borders, and paddings) otherwise a logical page break will occur. Alternatively, an entire element (and all embedded elements) can be made to appear in their entirety (or a logical page break will occur) by applying the "page-break-inside" style property to that element.

In FinerEdge Publisher, a logical page break does not necessarily mean that a physical page break will occur at that time. Let's consider a simple case where multiple columns are flowing down the page from a TABLE element. When a PAGEBR element is seen, the remainder of the current column will appear on the next page while the subsequent columns within the table will still be correctly formatted on the current page prior to the actual physical page break occurring.

Important: When physical page breaks do occur in FinerEdge Publisher, all active elements are visually closed with respect to margins, borders, and paddings, and all page areas are formatted. On the next page, the previously active elements are again visually opened again with respect to their margins, borders, and paddings. Regardless of elements being nested, to any level, within each other (e.g., tables within tables), FinerEdge Publisher will still properly format all elements that cross page break boundaries, no matter how many page breaks occur prior to elements being completely formatted.

The line break element "BR" operates in the same manner as the BR element in HTML. The amount of vertical spacing depends upon the current font-family, font-size, and line-height style properties.

» Back to the Table of Contents. «

Creating and using styles

The FinerEdge Publisher elements do not directly define style-related attributes themselves. Instead, all style-related formatting comes from style properties that adhere to the W3C's Cascading Style Sheet (CSS) specification.

Style properties can be easily updated in FinerEdge Publisher by using the built-in style property editor. The style property editor is accessible from the applicable element dialogs or from the STYLE element editor. You can also use the result of FinerEdge Publisher expressions as values assigned to any style property.

A number of elements in FinerEdge Publisher (i.e., SPAN, DIV, TABLE, etc.) define a standard XHTML attribute called "style" where you can freely specify any style properties that will be applied to the individual elements. These are called "in-line" style properties as they are applicable to only the element where they are defined. An example of applying a "bold" style to the text "Hello there" is as follows:

<SPAN style = "font-weight:bold">Hello there</SPAN>

Style properties can also be defined within the document to be subsequently reused throughout the rest of the document in a consistent fashion. These style property definitions are enclosed in an XHTML STYLE element pair. In addition, these style properties can be defined and reused in two different ways throughout the document: by "class" or by "id".

One of the ways to define style properties for reuse throughout the document is by "id". By "id" simply means that you apply a name to the style properties and then subsequently use that name with an XHTML attribute called "id" within various elements. An example of defining and using an "id" style is as follows:

<STYLE>
#myid { font-family:'Helvetica'; font-weight:bold; font-size:14pt }
</STYLE>

<SPAN id = "myid">Hello there</SPAN>

Another way to define style properties for reuse throughout the document is by "class". By "class" means that you apply a name to the style properties within a specific type of element and then subsequently use that name with an XHTML attribute called "class" on that type of element.

You can also apply style properties to be used with a specific type of element anytime that element is used by simply not including a user-defined name (i.e., only the element type itself is given). Some examples of defining and using "class" styles are as follows:

<STYLE>
SPAN { font-size:10pt }
SPAN.myclass { font-family:'Helvetica'; font-weight:bold; font-size:14pt }
</STYLE>

<SPAN>Hello there</SPAN>
<SPAN class = "myclass">Hello there too</SPAN>

» Back to the Table of Contents. «

Using SPAN elements

A SPAN element is created and updated using the IDE's built-in SPAN element dialog. SPAN element pairs are XHTML general purpose in-line elements. By "in-line" element, we mean that the SPAN element is used within text to vary one or more style properties of that text. Examples of this are bolding a word or phrase, changing the font, changing the color of text, etc.

SPAN elements may be freely embedded within other SPAN elements if desired. Only the text within the SPAN element pair is affected by the style properties that are applied to the SPAN. When the end SPAN element is seen, the style properties revert back to the settings that were active prior to the SPAN element being processed. An example of an in-line SPAN is as follows:

<SPAN style = "color:blue">Hello there</SPAN>

While SPANs are always "in-line", you can also define them as in-line "box" spans. Box spans have an explicit width specified by the style property "width" and can be multi-line (with a variable height or an explicitly specified height).

The entire "box" is formatted within the scope of the currently formatted line of the surrounding parent element, which may be another SPAN, DIV, TABLE, etc. An example of a "box" SPAN is as follows:

<SPAN style = "width:1in">Hello there<BR/>to you!</SPAN>

» Back to the Table of Contents. «

Using DIV elements

A DIV element is created and updated using the IDE's built-in DIV element dialog. DIV element pairs are XHTML general purpose block elements. By "block" element, we mean that the DIV element is used to vary one or more style properties within a block of text.

A block element implicitly begins and ends with a line break. However, DIV elements can also be embedded within other DIV elements or within a specific column of a TABLE element for precise formatting. An example of a DIV element is as follows:

<DIV style = "color:red">Hello there.<BR/>This is a test.</DIV>

» Back to the Table of Contents. «

Using TABLE elements

A TABLE element is created and updated using the IDE's built-in TABLE element dialog. A TABLE is a "block" element like the DIV, but with more than one column specified. Also, a TABLE element can be compared with XHTML's TABLE element.

FinerEdge Publisher TABLEs can be embedded within other TABLE or DIV elements. TABLE elements can accommodate multiple different types of columnar layouts as follows:

●	Grids with fixed height rows
●	Tables with variable height rows
●	Newspaper-style columns where rows are not synchronized
●	Tables that automatically advance columns at the end of each page

When constructing tables using the TABLE dialog, either an XHTML TR/TD a DIV/COLBR table model can be selected. Grids and tables with variable height rows are normally constructed using the TR/TD model whereas newspaper and automatic column break tables might benefit from using the DIV/COLBR model. COLBR is an alternative column break mechanism (i.e., advance to the next column or wrap to the next row) that has it's own advantages, especially when conditionally formatting tables.

The familiar XHTML TR and TD elements can be used within FinerEdge Publisher TABLE elements. Any style information specified for TR elements will be applied to the enclosed TD elements. In addition, the TABLE element also has an alternative "cellstyle" attribute that can directly apply style properties to all enclosed TD elements.

The HEADER element can surround one or more beginning table rows. When present, the HEADER rows will be repeated on subsequent pages for a table when a physical page break occurs. Furthermore, since TABLE elements can be embedded, each table can declare it's own HEADER rows that will all be repeated over physical page breaks. HEADER elements can also be implicitly declared by using the corresponding TR header attribute.

» Back to the Table of Contents. «

Using PAGEAREA elements

Header, footer, left, and right PAGEAREA elements can be used with FinerEdge Publisher documents. Any combination of SPAN, DIV, and TABLE elements may appear within PAGEAREA elements. In addition, page numbers, dates, times, and document references can also be formatted into any of the PAGEAREA elements.

PAGEAREA elements are normally defined near the beginning of a document and prior to any document formatting. PAGEAREA elements can be individually specified for the first page, remainder of the document, odd numbered pages, and even numbered pages. Left and right page areas might be used to format, for example, document thumb tabs.

PAGEAREA elements can also be redefined on-the-fly in a document if desired. When PAGEAREA elements are re-defined after formatting has begun for a particular page, the changed PAGEAREA elements are queued and will appear starting on the subsequent pages.

» Back to the Table of Contents. «

Using a PAGEBOX element

If the PAGEBOX element is used in a document, it must be located near the beginning of the main METHOD and prior to any formatting occurring. However, non-formatting elements (e.g., conditional elements) may precede the PAGEBOX element.

The PAGEBOX element allows document authors to explicitly set the physical page size, page orientation, document margins, odd/even page gutter, etc. In addition, the PAGEBOX element also allows a document author to specify a particular device name where output will automatically be directed when printing the document.

» Back to the Table of Contents. «

Updating the outermost DOCUMENT element

When using the FinerEdge Publisher IDE, the XML prolog, Document Type Definition (DTD), and external entity Processing Instructions (PI) are not directly updated within the editor window. Instead the XML prolog and FinerEdge Publisher DTD are automatically inserted into the applicable document entities. The external entities are updated from the IDE's entity pane that appears on the right-hand side of both the visual designer and markup views.

In addition to the XML prolog and DTD, the outermost DOCUMENT element is not directly updateable. Instead, the attributes of the DOCUMENT element are updated by selecting the Entity Properties dialog from the entity pane. For a document entity, you can set a default font-family and font-size, override date and time formats, currency symbols, specify an overall background color or image, and much more.

However, most of the Entity Properties dialog's fields will not be accessible if the checkbox "Document entity" is unchecked. In this case, the current entity being edited is a module entity and contains only methods. This is in contrast to a document entity which has an XML prolog, DTD, and document element as well as methods of it's own.

» Back to the Table of Contents. «

Using variables in documents

Once a person understands how FinerEdge Publisher documents are created and rendered in various output formats, the first question is usually "how do I get my data into the document?" The answer is by using FinerEdge Publisher variables.

FinerEdge Publisher variables handle whole numbers, floating-point numbers (including currencies), dates, times, and small to large strings of text. Variables in FinerEdge Publisher can even be array elements if desired. Variables can also be manipulated directly in FinerEdge Publisher expressions using a wide array of built-in functions for advanced string manipulation capabilities.

String variables can be up to 4095 characters in length if the variable will be utilized within any expression. However, if the variable is simply output into the document with the VAR element, it can be up to 2 billion characters in length (such as a database memo field, etc.). In this case, carriage return, linefeed, and carriage return/linefeed character combinations are reinterpreted as BR elements.

The three classes of variables in FinerEdge Publisher are local, global, and external. Local and global variables are created by a document author within the scope of the document. Local variables are created within a particular method and automatically destroyed when that method is exited. In contrast, global variables begin with the character "!" and are also created within a particular method. However when the method is exited, the variable is not destroyed and is subsequently visible to all other methods as well.

Most local and global variables are created and updated by using a SET element. The SET element uses two attributes, a variable name and an expression. The variable is assigned (set) to the resulting value and type of the evaluated expression. If the variable does not exist, it's first created prior to setting it's value and type. Examples of SET elements are as follows:

<SET var = "numVal" expr = "2.4+1.7"/>
<SET var = "numVals[1]" expr = "numVals[1]+10"/>
<SET var = "numStr" expr = "'This is'"/>
<SET var = "numStr" expr = "numStr+' a test'"/>

The third class of variables in FinerEdge Publisher are external variables. External variables begin with the character "@" and are created by either the host application (i.e., a program), FinerEdge Publisher database queries, or XML data files.

If you're deriving your data from, say, an XHTML form, you might want to then pass that data into the document. However, if the data is accessed from a database, you might be better off having FinerEdge Publisher directly access the data and automatically create the external variables for you. Regardless of how the external variables are created and populated, they all appear to the document author as reusable variables that are part of the document.

All FinerEdge Publisher variables can be output into a rendered document as part of the normal document flow. The variables can be output into the document by using the VAR element. The VAR element merges the contents of variables into the document flow at any point desired and as many times as necessary. Examples of VAR elements are as follows:

<VAR expr = "numVal[1]"/>
<VAR expr = "numStr+' test'"/>
<VAR expr = "@Invoice_CustNumq"/>
<VAR expr = "'('+@Invoice_CustAmount+')'"/>

» Back to the Table of Contents. «

Using recordsets and drilldowns

External variables are organized into sets that are most efficiently accessed at the same time. These sets of variables are called FinerEdge Publisher recordsets. The format of an external recordset variable is as follows:

@RecordsetName_VariableName

The actual names of the RecordsetName and VariableName parts of the variable name are set either by the hosting application, FinerEdge Publisher database queries, or XML data file tag names. Please refer to the FinerEdge Publisher reference manual for more information regarding recordsets and drilldowns.

Recordsets can be broken down into two basic types: single record and multiple record. When the variables for the recordset are populated, if there exists only one applicable or intended record, then the recordset type is single record. If there exists multiple applicable records, then the recordset type is multiple record.

When variables for a single record recordset are used, no additional action other than simply referencing the variables is necessary. In contrast, when the variables for a multiple record recordset are used, the document author must first invoke a "drilldown" by using the RECORDSET element.

If the recordset was a result of a FinerEdge Publisher database query or an XML data file, the applicable FinerEdge Publisher elements can be automatically generated by either the built-in Query Designer or XML element editor or both.

» Back to the Table of Contents. «

Using conditional elements

A number of elements in FinerEdge Publisher affect how the document flow is constructed in terms of conditional actions. Examples of conditional elements in FinerEdge Publisher are: IF, ELSEIF, ELSE, SELECT, and CASE. These elements are created and updated by the applicable IDE's built-in editors and can be easily constructed at any point within any method element pair.

The IF, ELSEIF, ELSE, SELECT, and CASE elements are synonymous to the way that the corresponding statements in almost any computer language would be used. The main difference is that in FinerEdge Publisher you're affecting both other elements and text with the conditional elements. Please refer to the FinerEdge Publisher reference manual for a detailed explanation of any of these conditional elements.

» Back to the Table of Contents. «

Using loop elements

A number of elements in FinerEdge Publisher affect how the document flow is constructed in terms of iterative actions or loops. Examples of loop elements in FinerEdge Publisher are: FOR and WHILE. These elements are created and updated by the applicable IDE's built-in editors and can be easily constructed at any point within any method element pair.

The FOR and WHILE elements are synonymous to the way that the corresponding statements in almost any computer language would be used. The main difference is that in FinerEdge Publisher you're affecting both other elements and text with the loop elements. Please refer to the FinerEdge Publisher reference manual for a detailed explanation of any of these loop elements.

» Back to the Table of Contents. «

Using additional methods

FinerEdge Publisher encapsulates elements, text, and styles into reusable components called methods. Methods are created and updated by the IDE's built-in method editor. An example of a method named "Test_Method" that uses two parameters, one by value and the other by reference, is as follows:

<METHOD name = "Test_Method" params = "strValue1='',ByRef strValue2=''">
...
</METHOD>

Parameters have initialization values that follow the parameter names (e.g., strVar=''). Initialization values determine the type of the parameter (i.e., string, number, or float). If a calling method uses another method while passing in parameters that do not correspond to the declared parameter types, the caller will be given an error. Furthermore, parameter initialization values imply that the parameters are optional and also give the visual designer default values to depict the method and its contents.

One special method within the main document entity is declared as the main method. The main method is processed first and when the main method completes, all document processing is also complete. As such, all other methods are used (called) either directly or indirectly from the main method. In addition, any method may use any other method except the main method. Methods are used (called) by utilizing the corresponding IDE built-in editor. An example of using the previously declared method is as follows:

<USE name = "Test_Method" params = "'Hello there',strValue"/>

As previously stated, methods can pass parameters when used (called). Method parameters can be passed either by value (the default) or by reference. When parameters are passed by value, the value of the passed variable is unaltered when the method exits. In contrast, when parameters are passed by reference, any change to the value of the parameter variable that was made in the method will be reflected back into the passed variable. As such, constant values may not be passed to a "by reference" parameter.

Methods may be located within document entities or within a module entities (as defined by the IDE's Entity Properties dialog accessed from the entity pane within the visual designer or markup views). Any methods within module entities can also call any other methods that are located in other module entities.

» Back to the Table of Contents. «


Introduction

This tutorial guides an individual through the steps necessary to create FinerEdge Publisher database queries using the built-in Query Designer located within the IDE. FinerEdge Publisher queries are created by simple point, click, and drag mouse methods and selecting or entering information into the query designer.

In addition to creating database queries, this tutorial will assist an individual in generating an entire FinerEdge Publisher document from the newly created query with the push of a single button. Formatting themes can also be applied to the query to allow an individual to control the generated document's "look and feel".

The query designer can even generate individual parts of a document that are then inserted into existing documents. That way, you can regenerate just the portion of the document that corresponds to either an updated query or a new query.

» Back to the Table of Contents. «

The FPSample database

A small sample Microsoft Access database called "FPSample.mdb" was supplied for use with this tutorial and was copied onto your workstation by the FinerEdge Publisher installation. By default, the database "FPSample.mdb" is located in the directory:


The sample database has four tables defined in it as follows:

Customer	A table that contains customer records.
Inventory	A table that contains the current inventory of stock items.
InvGeneral	A table that contains general information regarding invoices.
InvDetail	A table that contains detailed line items for each invoice.

For each invoice found in the InvGeneral table, we'll be accessing the detailed invoice line items found in the InvDetail table. In addition, the InvGeneral table contains a customer number that refers to the Customer table and the InvDetail table contains a inventory stock code that refers to the Inventory table.

The one-to-many or multiple record queries in the sample database are represented by the InvGeneral table (i.e., one or more invoices) and the InvDetail table within the InvGeneral table (i.e., or more invoice line items for each invoice).

» Back to the Table of Contents. «

An initial example

1. Create a new document

The first step in creating our queries for the sample database described above is to start the FinerEdge Publisher IDE from your menu. Then press the first button on the top buttonbar on (i.e., "Create a new document"). Select the option "Create a new document and database definition" and press the OK button.

The Query Designer is then displayed on your screen followed by the standard system dialog box to select an ODBC data source. The FPSample data source was previously established by the FinerEdge Publisher installation. Please select FPSample and press the OK button.

2. Add tables and fields

After selecting the newly created sample database ODBC data source, a checklist of tables within the database is shown next. A new connection and query will also appear in the main Query Designer window.

For our first example, check only the Customer table, and press the OK button. A checklist of fields is then shown. Check all of the fields by pressing the "Check All" button followed by the OK button. The selected table fields are shown under the new query in the main Query Designer window.

3. Set the generation fields

Select the query by clicking your mouse on the "Q" icon in the main Query Designer window. Next, select "Two-column Gray" for the "Generate theme". Notice the image that appears in the form. This is a sample of what the theme "Two-column Gray" will generate for you.

4. Generate and view the document

Exit the Query Designer by pressing the OK button in the upper right corner of the Query Designer window. You'll then be asked to save the FinerEdge Publisher SQL file. Please save the FinerEdge Publisher SQL file as "FPSample". You'll then be asked if you'd like to generate the document based upon the newly created FinerEdge Publisher SQL file. Please press the "Yes" button.

Back in the FinerEdge Publisher IDE, you'll see your newly generated document. Now press the button "Select Document Generation View" located on the top buttonbar. You'll see a number of customer records each displayed in its own box within a two-column format. Press the "Select visual designer" button located on the top buttonbar to return to the visual designer view.

5. Change the generation fields and regenerate the document

To change the generation fields on an existing query and re-generate the document, first select the QUERYDATA element and then press the "Edit the current element" (i.e., Tag/Edit) button located on the top buttonbar (or just double-click on the QUERYDATA element). You'll then enter the Query Designer where you can again view the FinerEdge Publisher SQL file.

Again, select the query by clicking your mouse on the "Q" icon in the main Query Designer window. In the query fields below the main Query Designer window, select "TABLE" for the "Generate format". Notice the image that appears. This is an example of what the theme "Two-column Gray" will generate for you in a TABLE format as opposed to a FIELD format (which we previously generated).

Next, press the "Gen Doc" button. Subsequently exit the Query Designer by pressing the OK button in the upper right corner of the window. The newly generated document with a "Generate format" of TABLE is shown in the IDE visual designer.

Now press the button "Select Document Generation View" located on the top buttonbar. You'll see the same number of customer records displayed in a table format which also supports variable height rows. Press the "Select visual designer" button located on the top buttonbar to return to the visual designer view.

At this point, you may want to optionally explore some of the themes by repeating this step for the available theme names in the query's "Generate theme" selection list.

» Back to the Table of Contents. «

A drilldown example

It would be nice if everything fit into the simple model described by the example above. While some cases do, most others require more involved relationships between queries.

Within queries, joins can assist in combining tables to form recordsets of data that can then be shown in a document. FinerEdge Publisher supports inner, outer left, outer right, and outer full joins in the Query Designer.

Note: Not all ODBC drivers support the same features concerning outer joins. FinerEdge Publisher detects the capabilities of the ODBC driver and displays warning messages if certain features are used which are not supported by the particular ODBC driver.

As is consistent with the SQL92 specification, inner joins are handled by simply specifying two or more tables in the query with an appropriate "Where" clause that relates the tables to each other. In contrast, outer joins are accomplished by specifying one or more "Join" elements within the Query Designer.

As previously stated, joins assist us in combining the fields of two or more tables together into a single recordset within a query. But if you consider our sample database's tables, joins can only help out with two cases (i.e., InvGeneral to Customer and InvDetail to Inventory). Also, since we'll want to report on the customer separately, we can only use one of the join types described above to combine the InvDetail and Inventory tables.

What we'd like to accomplish in this example is to create multiple queries in a embedded hierarchical structure. Each invoice is represented by an InvGeneral record that points to a Customer record and one or more InvDetail records.

In addition to structuring our queries, we'll want to use the results from one query, InvGeneral, to drive both the embedded queries Customer and InvDetail. All of this can be accomplished completely within the Query Designer.

1. Updating an existing FinerEdge Publisher SQL file

Let's begin this example where our previous example left off by first selecting the QUERYDATA element and then pressing the "Edit the current element" (i.e., Tag/Edit) button located on the top buttonbar. You'll enter the Query Designer where you can again view the existing FinerEdge Publisher SQL file.

Select the single existing query by clicking your mouse on the "Q" icon in the main Query Designer window. In the query fields below the main Query Designer window, type "Customer" for the query name to be consistent with our new queries we're about to create.

2. Adding the InvGeneral query

First select the connection and then press the "New" button located on the left side of the Query Designer under the tree display. A popup menu of choices is displayed for you. Select the choice "Insert Query for Connection". When prompted, check only the table InvGeneral. When subsequently prompted, check all fields to be added from the InvGeneral table. Change the query name to "InvGeneral". Press the "New" button and select the choice, "New Tables".

3. Adding the InvDetail query

First select the connection and then press the "New" button located on the left side of the Query Designer under the tree display. A popup menu of choices is displayed for you. Select the choice "Insert Query for Connection".

When prompted, check only the tables InvDetail and Inventory. When subsequently prompted for InvDetail, check only the fields "InvNum", "StockNum" and, "Quantity". When prompted for Inventory, check the fields "StockNum", "Description", and "UnitCost". Change the query name to "InvDetail".

4. Hiding fields from document generation

Click on the field "InvNum" of the table InvDetail and check the checkbox "Hide". Also, click on the field "StockNum" of the table InvDetail and check the checkbox "Hide".

5. Adding a calculated column

Let's take a moment to extend the joined query by adding another field, which will be the result of a calculation done on two previous fields. Select the table InvDetail, press the "New" button and select the choice, "Insert Calculated Field".

Leave the Table field blank. In both the Field name and Variable name fields, type "Cost". In the Expression field, either use the SQL expression editor to construct the expression or directly type in the following SQL expression:


Note: The Expression field can also be used to specify a nested "Select" in order to, for example, lookup and use a value in another table based upon a value appearing in this table.

6. Changing field options

In our new Cost field, set the Option field to "CURRENCY". Click on the field UnitCost of the table Inventory and also set the Option field to "CURRENCY". Then, click on the field Quantity in the table InvDetail and check the checkbox "Total" to create a column total for this field.

7. Specifying an inner join condition

To specify our inner join condition, click on the query InvDetail. In the Where field, either use the SQL expression editor to construct the expression or directly type in the following SQL expression:


8. Embedding queries within other queries

So far, we've defined our queries, and the tables and fields that exist within the queries. We've specified an inner join in one of the queries and created a calculated field in one of the tables of that join. Now we're ready to structure our queries. Click on the query InvDetail and drag (and drop) it onto the query InvGeneral. Choose the subsequent dialog box option "Embed item". This embeds the query InvDetail within the query InvGeneral. Likewise, click on the query Customer and drag (and drop) it onto the query InvGeneral. Choose the subsequent dialog box option "Embed item". This also embeds the query Customer within the query InvGeneral, but appearing before the embedded query InvDetail.

9. Driving embedded queries from outer queries

Now let's drive both of the embedded queries from the outer InvGeneral query. With FinerEdge Publisher's query designer, this turns out to be a relatively easy thing to do.

The basic idea is to construct the FinerEdge Publisher Recordset element's "expr" attribute for the queries Customer and InvDetail. And since we're only "using" the already populated variables from the InvGeneral query to construct the Recordset parameters, nothing more needs to be done to the InvGeneral query itself.

10. Driving the Customer query from the outer InvGeneral query

Click on the query Customer. In the Where field, either use the SQL expression editor to construct the expression or directly type in the following SQL expression:


The mnemonic "custnum" is a name we've just invented (i.e., it could be "xyz" if we wanted it to at this point). You'll see where we will use the mnemonic "custnum" in the next step.

Click on the button located to the right of the Parameters field to invoke the Query Parameters editor. In the Query Parameters editor, the Name field's selection list contains the mnemonics that were used in the Where field. First, select the mnemonic "custnum" from the Name field's list.

Press the Expression Editor button to the right of the Value field. In the FinerEdge Publisher Expression Editor select the FinerEdge Publisher variable "@InvGeneral_CustNum" from the list, press the "Paste" button, and press the "OK" button. Finally, press the "OK" button from the Query Parameters to copy the constructed query parameter into the Parameters field of the Customer query.

You've just directed the Customer query to be automatically driven by the results of the InvGeneral query. The combination of filling in the Where field (with parameter mnemonics) and filling in the Parameters field (using the parameter mnemonics just defined in the Where field) is what makes this happen.

11. Driving the InvDetail query from the outer InvGeneral query

Next, click on the query InvDetail. In the Where field, either use the SQL expression editor to construct the expression or directly change the following SQL expression from:


to:


Click on the button located to the right of the Parameters field to invoke the Query Parameters editor. First, select the mnemonic "invnum" from the Name field's list.

Press the Expression Editor button to the right of the Value field. In the FinerEdge Publisher Expression Editor select the FinerEdge Publisher variable "@InvGeneral_InvNum" from the list, press the "Paste" button, and press the "OK" button. Finally, press the "OK" button from the Query Parameters to copy the constructed query parameter into the Parameters field of the Customer query.

Like the Customer query, you've just directed the InvDetail query to be automatically driven by the results of the InvGeneral query while also preserving its previously specified inner join.

12. Set the generation fields for the queries

Now were ready for the final step prior to generating our document - selecting our formats and themes. These fields can be set at the same time for each of the three queries. (Note that different themes may be applied to each of the queries that are defined in a FinerEdge Publisher SQL file.)

First select the InvGeneral query. Set the "Generate format" to "FIELDS", and "Generate theme" to "Distinctive blue". Next, select the Customer query. Set the "Generate format" to "FIELDS" and "Generate theme" to "Distinctive blue". And finally, select the InvDetail query. Set the "Generate format" to "TABLE", and "Generate theme" to "Distinctive blue".

13. Generate and view the document

Just as we did in our previous examples, press the "Gen Doc" button and subsequently exit the Query Designer by pressing the OK button in the upper right corner of the window. The newly generated document is shown in the IDE visual designer.

Press the button "Select Document Generation View" located on the top buttonbar. Each page represents a different invoice. Press the "Select visual designer" button located on the top buttonbar to return to the visual designer view.

The FinerEdge Publisher Query Designer has a number of additional features such as defining table rules with expressions that determine when individual cells, columns, or rows of a table will be highlighted or separately styled. The Query Designer can also generate individual queries (or parts of a document) to the clipboard to be subsequently pasted into an already existing document. This allows new queries to be added or individual queries to be updated within an existing document. For more information, please refer to the IDE manual.

» Back to the Table of Contents. «


Introduction

An XML data file is a hierarchical structure of tags and tag attributes, and the data that is encapsulated by the tags. This tutorial guides a document author through the steps necessary to create a FinerEdge Publisher document from an existing XML data file.

An XML data file's purpose is to provide a structured format that facilitates the exchange of information over a network to include the Internet. From its early inception, XML data was sometimes referred to as the the "EDI" (or exchange format) of the future.

FinerEdge Publisher is capable of directly using one or more XML data files as input into a document. In addition, FinerEdge Publisher can simultaneously process input from one or more database data sources and data fed directly from an application while also using XML data files.

Document authors can generate an entire FinerEdge Publisher document from an XML data file by utilizing the built-in XMLDATA editor of the IDE. Alternatively, document authors can also automatically generate the elements necessary to process an XML data file to the Clipboard. The document author can then paste the generated elements directly into an existing FinerEdge Publisher document.

» Back to the Table of Contents. «

The sample XML data file

A sample XML data file called "XMLTest.xml" was supplied for use with this tutorial and was copied onto your workstation by the FinerEdge Publisher installation. The XML data file is located, by default, in the directory:


» Back to the Table of Contents. «

The XMLTest example

1. Create a new document

The first step in creating a FinerEdge Publisher document that processes the sample XML data file previously described is to run the FinerEdge Publisher IDE. Next, press the first button on the IDE's top button bar ("Create a new document"). Then select the option "Create a new document based on XML Data" and press the OK button.

The XMLDATA editor is then displayed followed by the standard system dialog to open a file. Locate the Docs directory and select the XML data file "XMLTest.xml" and press the OK button. The XML tree, showing a visual representation of the contents of the sample XML data file, is displayed within the XMLDATA editor.

2. Generate and view the document

Exit the XMLDATA editor by pressing the OK button. You'll then be asked if you'd like to generate the document based upon the XML data file that is currently displayed in the XMLDATA editor. Please click the "Yes" button.

In the FinerEdge Publisher IDE, you'll see your newly generated document in the visual designer view. Press the "Select document generation" button on the top buttonbar. You'll then see the contents of the XML data file in the rendered document output. Press the "Select visual definition" in the top buttonbar to return to the visual designer.

» Back to the Table of Contents. «

Creating and modifying XMLDATA tags

For documents that already exist, additional XMLDATA elements can be inserted from within the IDE by first pressing the "select markup definition" button on the top buttonbar. Then, select the location within the document where you desire the new XMLDATA element be placed and subsequently press the button "Create/edit an XMLDATA element" located on the IDE's top buttonbar.

From the standard system open file dialog, select an XML data file and press the OK button. The XML tree corresponding to the XML data file is then shown in the XMLDATA editor.

If you just want the XMLDATA element to be placed into your document, simply press the OK button. However, if you want the XMLDATA editor to generate all FinerEdge Publisher document elements that will allow access to the XML data file, press the "Generate to Clipboard" button followed by the OK button. Then, select the resulting XMLDATA element and subsequently paste the contents of the Clipboard into the selected location.

To modify an XMLDATA element, double-click anywhere on the applicable XMLDATA element. The XMLDATA editor is then displayed along with the corresponding XML tree. Make any changes necessary and then press the OK button.

» Back to the Table of Contents. «



Introduction

The FinerEdge Publisher FPWeb facility empowers an organization's outside customers and internal users with the ability to, from their browser, visually customize document definitions, save the customized document definitions for reuse, generate documents in all supported output formats, and view the generated documents. In addition, FPWeb utilizes HTML elements, CSS styles, and standard JavaScript within client web browsers for maximum compatibility and security.

Initially, site administrators create any number of document templates by utilizing the built-in query designer of the FinerEdge Publisher IDE. The document templates establish the basic structure and query access for the documents, and also define how queries are related to each other in drill-down (i.e., one-to-many) situations. Within a particular query for a template, all possible fields are normally defined, but may be later hidden by a user when customizing their own document definition. A sample document template called "FPSample.fsq" that is configured for use with FPWeb was included as part of your FinerEdge Publisher installation.

In addition, formats and themes are applied to document templates, which can also be altered by a user when customizing a document definition based upon a template. The site administrators should save all document templates into a common directory, which is identified by the FPWeb configuration file as the template repository. Users of FPWeb can then access the templates in the template directory (in a read-only manner) in order to create their own customized document definitions based upon the templates.

The FPWeb facility is in contrast to another facility of FinerEdge Publisher. That is, the ability for a document author to create precise and detailed document layouts via the built-in WYSIWYG or markup editors of the IDE, which may also utilize the query facility or XML data as input while generating documents. The document author can then visually create a front-end form to optionally have users supply certain initial information and then automatically generate either an ASP or JSP web-enabled process, where the front-end form is translated into HTML and embedded within the ASP or JSP process.

The differences between these two facilities can be summarized as follows. The documents produced by FPWeb are easily customizable by users that have little or no knowledge of document publishing techniques. But due to the simplified interface of FPWeb, the document formats can only be altered within the prescribed structure of the formatting themes. In contrast, documents, front-end forms, and automatically generated ASP and JSP processes produced by the IDE can dramatically and precisely vary their look and feel. While these type of documents can be accessed and generated by any user, they are not customizable utilizing the more constrained FPWeb facility.

The facilities of FPWeb are available as both an Active Server Pages (ASP) and Java Server Pages (JSP) implementations. Both FPWeb ASP and JSP versions look and operate in exactly the same way. As such, this tutorial is applicable to either the ASP or JSP versions of FPWeb. In addition, both of the FPWeb ASP and JSP versions come with an on-line HTML help page that is accessible from the main FPWeb menu.

Important: If FPWeb has not been previously setup by your organization, it must first be configured and adapted to your user signon prior to being used. The setup instructions for FPWeb are located in the FinerEdge Publisher Programmer's Guide.

» Back to the Table of Contents. «

FPWeb Fundamentals

On the FPWeb main web page, a horizontal menu consisting of only "Open Template", "Open Definition", "Delete Definition", and "Help" are shown. However, this menu is expanded with additional menu items after a template or document definition has been opened.

The "Open Template" menu item shows a list of available document templates that can be subsequently customized and saved into your own document definition folder (i.e., under your user signon). The "Open Document" menu item shows a list of your own document definitions that have been previously saved. In either case, selecting and opening a template or document definition will show one or more queries that exist within the definition. Also, after opening a template or document definition, the additional menu items "Save Definition", "Save As Definition", "Generation Options", and "Generate Documents" are shown.

For example, opening a template such as the supplied "FPSample.fsq" and then selecting the "Save Definition" menu item will save the FPSample definition into your own document definition folder. Subsequently opening your document definitions will show the document definition previously saved. Alternatively, if you wish to save a template or document definition as another name, you can select the "Save As" menu item. The "Save As" menu item will ask a new name be entered, but otherwise perform the same action as the "Save" menu item. Likewise, selecting the "Delete Definition" menu item will first show your saved document definitions. Selecting a particular document definition for deletion will remove that document definition from your document definition folder.

The "Generate Options" menu item will allow you to modify document definition options affecting the entire document. Generate options include optional header text, a header image, image position, footer text, date/time formats and delimiters, and decimal, thousand, and currency delimiter characters. Images must be previously uploaded and placed somewhere under your user signon folder. Furthermore, only relative names should be used to specify images (i.e., non-absolute names that are relative to your signon folder).

The "Generate Documents" menu item has been specially highlighted. This menu item allows multiple document output formats to be simultaneously generated and viewed. Many times, a user might simply open a previously saved document definition and immediately select the "Generate Documents" menu item without changing the document definition in any way. Since most of the information for a document may come from a repository that is continually updated, this particular sequence (of menu items) is commonly employed.

» Back to the Table of Contents. «

Queries and Fields

When a template or document definition has been opened, a list of queries within the definition is shown following the main menu. For each query, the name of the query, description of the query, and a "Select" button is displayed. Pressing the "Select" button for a particular query will show the options for the query as well as a list of fields that exist within the query. If any options or fields are modified for the query, they will be automatically saved when a different query is selected.

After a particular query is selected, the options for the query are shown following the query list. In addition, the fields within the query are displayed following the query options. Finally, optional record filters are shown following the query fields. The query format and theme selections affect the visual appearance of the generated documents. In addition, the format for any theme may have a "field" look and feel or be oriented in a table format.

The fields within a particular query can be hidden or shown by clicking the "Hidden" checkbox on/off. Furthermore, the order of the fields in the generated documents can be rearranged by clicking anywhere within a particular field's options and pressing either the "Move Up" or "Move Down" buttons. These actions are performed locally within the browser for a more interactive user experience.

The width of a field is optional and alters the default width of either fields or table columns in the generated documents depending upon the query format chosen (i.e., field or table). The definitions for the units of measurement for the width are discussed in the on-line help.

The sort options for a field determine if the query records will be sorted in ASCending order, DESCending order, or not sorted. If multiple fields specify a sort for a query, the sort will be performed in the order that the fields appear (in the field list).

Lastly, fields may optionally show a final totals record when the query's format is set to "table". A total for a particular field is a summation of the values for that field (displayed as a table column). As such, a field that specifies a totals must be a numeric type such as an integer or floating point value (otherwise a totals will not be displayed for that field).

» Back to the Table of Contents. «

Record Filters

Record filters are optional and affect the records that are shown (or not shown) in both field and table formats. Up to three record filters may be optionally specified. If more than one record filter is given, all record filter conditions must evaluate to true for a particular record to be shown.

Each of the three possible record filters is composed of a field, operation, and a value. The field is the name of a particular query field, which is compared against the record filter value(s) using the selected comparison operation. The value(s) supplied must be relevant to the type of field selected, otherwise an error message will be shown to the user when the documents are generated (e.g., textual values cannot be given for numeric fields).

Multiple values may be given for the "equals" and "not equals" operations separated by commas. With the operation "equals", any of the values given match against the field whereas with the operation "not equals", all of the values must not match against the field. With the operation "between", exactly two values must be given and are inclusive of those values. With the operations "begins with", "ends with", and "contains", only one value can be given.

Note: A special case arises when using the operation "between" with dates and timestamp fields (i.e., those fields having both a date and time part). In this case, the second date value will append a time of 23:59:59 (i.e., one second prior to midnight). As such, all timestamps up to the end of the day for the second value will successfully match the filter condition.

» Back to the Table of Contents. «


Introduction

FinerEdge Publisher IDE themes can be used by the query editor (i.e., database definition) to enhance the look and feel of documents that are automatically generated.

Themes are loaded by the IDE from an external file called a theme file. The theme file contains one or more theme definitions. The theme definitions themselves are described with a tag language that is presented in the next topic.

The theme file name is set by the "Theme file" field of the IDE's preferences dialog. As a naming convention, a theme file normally uses the ".thm" extension. A standard theme file comes with every FinerEdge Publisher installation and is located in the "Environ" subdirectory along with the catalog.

» Back to the Table of Contents. «

Theme file definition

The following information in this topic describes the structure of the theme file and each of it's respective elements.



The theme file consists of one or more <theme> definitions.



Each <theme> definition consists of a THEME tag pair along with various embedded information tags. The <description> will appear in the applicable combobox list of the query editor. The <fieldimage> and <tableimage> attributes designate BMP files that are located in the same directory as the theme file itself. Each of these images should be a one-half (i.e., 50%) sized sample illustrating the theme's look and feel for both a type of Field and a type of Table.

1. Theme tags that can be used with both Field and Table types.



The content of this tag must contain style properties. These style properties are used to format the document header for all pages. Note: Only the primary (i.e., outermost first query) is utilized to format the header.



The content of this tag must contain style properties. These style properties are used to format the document footer for all pages. Note: Only the primary (i.e., outermost first query) is utilized to format the footer.



At each RECORDSET level and prior to the RECORDSET's loop, a title is formatted into the document. The exact text depends upon the particular data source.

The attribute "orientation" is used with a type of Field. When the value of "orientation" is "INSIDE", the title is formatted inside of the <box> tag (otherwise, the title is formatted outside of the <box> tag). The content of this tag must contain style properties. These style properties are used to format the title (obtained from the data source) into the document.

2. Theme tags that are used with only Field types.



At each RECORDSET level and surrounding the RECORDSET's loop, an optional TABLE tag can be used to enable multi-column output. The attribute "cols" defines the resulting TABLE's columns. The content of this tag must contain style properties. These style properties are used to format the TABLE element.



At each RECORDSET level and within the RECORDSET's loop, an optional BOX tag can be used to surround all of the fields in the record. The content of this tag must contain style properties. These style properties are used to format the DIV element.



At each RECORDSET level and within the RECORDSET's loop and the box's DIV element, a required FIELD tag pair is used to define the FPML tags that comprise each field of the record.

The content of this tag must contain FPML tags. These FPML tags are used to format the tags of the field. The FPML tags are enclosed within a method for the particular field. This method is passed the following parameters:

strLabel -


strValue -


strWidth -


strStyle -


3. Theme tags that are used with only Table types.



At each RECORDSET level and surrounding the RECORDSET's loop, a TABLE tag pair is used to create the table. The attribute "type" indicates if the TABLE's column widths should be initially calculated percentage values (i.e., Normal) or automatically adjusted (i.e., Adjust). The content of this tag must contain style properties. These style properties are used to format a TABLE element.



At each RECORDSET level and prior to the RECORDSET's loop but within the table's TABLE element, the "caption" style properties provide the formatting for the first row of cells in the table. The content of this tag must contain style properties. These style properties are used to format the table's "caption" cells.



At each RECORDSET level and within the RECORDSET's loop, the "body" style properties provide the formatting for the inner rows of cells in the table. The content of this tag must contain style properties. These style properties are used to format the table's "body" cells.



At each RECORDSET level and after the RECORDSET's loop but within the table's TABLE element, the "total" style properties provide the formatting for the last row of cells in the table. The content of this tag must contain style properties. These style properties are used to format the table's "total" cells.



At each RECORDSET level and within the various areas of the table (i.e., caption, body and total), the "column" style properties provide additional formatting for entire columns in the table. Note: Rows, columns and individual cells can also be formatted by employing rules, which utilize the <custom> styles defined below.

The attribute "apply" indicates the areas of a table where this tag applies. The attribute "cols" is defined as follows:

<columns>:


<column>:



The content of the <column> tag must contain style properties. These style properties are used to format specific columns of the table's cells.



The <custom> entries appear in the "Style name" control of the IDE's Rules Editor, which is accessed from query editor (i.e., database definition). The content of the <custom> tag must contain style properties. These style properties are used when Rules evaluate to True and are then applied to specific cells of a table.

» Back to the Table of Contents. «


Introduction

FinerEdge Publisher IDE XML tag definitions can be used to automate XML tag creation when used in conjunction with the IDE's query editor (i.e., database definition) and the "Text" output driver. XML tags are loaded by the IDE from an external file called an XML tags file. The XML tags file contains one or more XML Tag definitions. The XML tag definitions themselves are described by a language that is presented in the next topic.

The XML tags file name is set by the query editor of the IDE and stored within the OPTIONS tag of the FinerEdge Publisher SQL (.fsq) file. As a naming convention, an XML tags file uses the ".fxt" extension. In addition, a sample XML tags file is located in the directory:


» Back to the Table of Contents. «

XML tags file definition

The following information in this topic describes the structure of the XML tags file and each of it's respective elements.





Each <tag> definition consists of a number of attributes as follows:

name	The required unique name of the tag. If the tag's name is not unique, an error will result when reading the tag file.
desc	The required description of the tag.
xml	The XML name of the tag. If this attribute is not given, the value of the "name" attribute is used instead.
type	If the value is "Group" (default), the query and group select lists are populated. However, if the value is "Field", the field select lists are populated.
group	Indicates one or more group names where the group or field can be used. If a group name is "*", the group can be used at the base level. If no group names are specified, the group can only be used at the base level.
priority	Indicates if the use of the group or field tag is required, recommended, or optional.
primary	One field can be designated as containing a uniquely identifying value, such as a Product ID.

Each <options> definition consists of a number of attributes as follows:

name	The required unique name of the options definition. If the option definition's name is not unique, an error will result when reading the tag file.

When the "select" attribute is not used with any of the options, the option names populate a list which is subsequently used when the tag is chosen. Each <option> definition consists of a number of attributes as follows:

name	The required name of the option.
desc	The optional description of the option.
select	For a type of "Field" only, the value of the data field is compared with each of the values of this attribute. If a match is found, the value of the "name" attribute is substituted in place of the data field. A final value of "ELSE" can be used for a default condition.

Each <use-options> definition consists of a number of attributes as follows:

name	The name of the options definition to use with the tag.

» Back to the Table of Contents. «