FinerEdge Publisher Support Documents

FinerEdge Publisher IDE Manual.
FinerEdge Publisher Reference Manual.
FinerEdge Publisher Demonstration Tutorial.
FinerEdge Publisher Author's Guide (this document).
FinerEdge Publisher Programmer's Guide.
FinerEdge Publisher Updates and Acknowledgments.

FinerEdge Publisher Author's
Guide

Version 4.5.160301.0

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 page rules
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


IDE Theme File

Introduction
Theme file definition

IDE XML Tags File

Introduction
XML Tags file definition

Authoring FinerEdge Publisher
Documents

Introduction

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. «


IDE FPML
Tutorial

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 HTML 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 HTML 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 "class". By "class" means that you apply a name to the style properties and then subsequently use that name with an HTML attribute called "class" within various elements. An example of defining and using an "class" style is as follows:

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

<span class = "myclass">Hello there</span>

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 HTML 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 HTML 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 HTML'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

Tables that automatically advance columns at the end of each page

When constructing tables using the table dialog, either an HTML 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 HTML 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. The header elements can also be implicitly declared by using the corresponding tr header attribute.

» Back to the Table of Contents. «

Using page rules

Page rules allow document authors to explicitly set the physical page size, page orientation, document margins, odd/even page gutter, and margin rules. When page rules are used in a document, they must be applied prior to any normal flow formatting, otherwise the page rule will not be active until the next page is formatted. This also implies that page rules can be re-defined for subsequent pages in a document.

Page rules can also have margin rules that define a page's header, footer, left and right page areas within FinerEdge Publisher documents. Margin rules can also be separately specified for the first page, left page, right page (i.e., odd versus even pages), and blank pages.

Each margin rule references a div or table element that is declared with the style property "position" set to "running" along with a unique name. Running elements are not part of the normal flow of a document. Any combination of span, div, and table elements may appear within running elements in addition to page numbers, dates, times, and document references.

Each margin rule uses the "content" style property and the applicable unique name to refer to a particular running element previously declared. In addition, style properties can also be defined within margin rules that will be applied to the applicable running elements when formatting the document page areas.

» 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 HTML 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. «

Query Designer
Tutorial

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:

C:\Program Files\FinerEdge Software\FinerEdge Publisher\DB\FPSample.mdb

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 either an ODBC data source, OLEDB data link, or ADO data link. 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, OLEDB data link, or ADO data link, 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.

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:

Inventory.UnitCost * InvDetail.Quantity

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:

Inventory.StockNum = InvDetail.StockNum

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:

Customer.CustNum = @custnum

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:

Inventory.StockNum = InvDetail.StockNum

to:

InvDetail.InvNum = @invnum AND Inventory.StockNum = InvDetail.StockNum

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. «

XML Data
Tutorial

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:

C:\Program Files\FinerEdge Software\FinerEdge Publisher\Docs\XMLTest.xml

» 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. «

IDE Theme
File

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.

<theme file>:

<theme> [ <theme> ]...

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

<theme>:

<THEME description="<value>"
    [fieldimage="<value>"] [tableimage="<value>"]>
  [<title>|<table>|<caption>|<body>|<total>|
    <column>|<table>|<box>|<field>|<custom>]...
</THEME>

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.

<header>:

<HEADER>...</HEADER>

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.

<footer>:

<FOOTER>...</FOOTER>

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.

<title>:

<TITLE [orientation="OUTSIDE|INSIDE"]>...</TITLE>

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.

<table>:

<TABLE cols="<cols>">...</TABLE>

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.

<box>:

<BOX>...</BOX>

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.

<field>:

<FIELD>...</FIELD>

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 -

The label of the field.

strValue -

The value of the field.

strWidth -

The width of the field.

strStyle -

Optional style properties of the field (not currently used).

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

<table>:

<TABLE [type="Normal|Adjust"]>...</TABLE>

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 tables'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.

<caption>:

<CAPTION>...</CAPTION>

At each recordset level and prior to the recordset's loop but within the 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.

<body>:

<BODY>...</BODY>

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.

<total>:

<TOTAL>...</TOTAL>

At each recordset level and after the recordset's loop but within the 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.

<column>:

<COLUMN cols="<columns>" apply=
  "ALL|CAPTION|BODY|TOTAL|CAPTIONANDBODY|CAPTIONANDTOTAL|BODYANDTOTAL">
  ...
</COLUMN>

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> [, <column> ]...

<column>:

  L|R <start column> [- <end column>]

"L" and "R" are defined as relative to the leftmost column or relative to the rightmost 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.

<custom>:

<name>...</name>

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. «

IDE XML Tags
File

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:

C:\Program Files\FinerEdge Software\FinerEdge Publisher\Docs\FPDemo.fxt

» 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.

<XML tags file>:

<tag>|<options> [ <tag>|<options> ]...

<tag>:

<TAG name = "<value>"
    desc = "<value>"
    [ xml = "<value>" ]
    [ type = "Group|Field" ]
    [ group = "<value> [| <value>]"]
    [ priority = "Required|Recommended|Optional" ] >
    [ primary = "Yes|No" ] >
  [ <use-options>|<option> ]...
</TAG>

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.

<options>:

<OPTIONS name = "<value>" >
  [ <option> ]...
</OPTIONS>

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.

<option>:

<OPTION name = "<value>"
    [ desc = "<value>" ]
    [ select = "<value> [| <value>]" ] />

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.

<use-options>:

<USE-OPTIONS name = "<value>" />

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. «

Copyright © 2016 FinerEdge Software. All rights reserved.