Form Template design

 Data Hierarchy

The data hierarchy describes the logical object model of all the components of the form template.

Beneath the Data hierarchy are three types of node:

□     Master pages

At least one master page must be defined.  Typically the form header/footer/logos – anything that should be repeated on each page, should be put inside the master page.  Also a Content Area must be defined, which is basically a box defining the boundaries for all the other form fields.  This ensures that form fields do not overlap with headers and footers on the master.  The Content area by default does not have a name it should be named and by default this should be called ‘content’.  This is critical when coding as un-named objects or subforms make referencing in script very difficult.

□     Subforms

There are two types of subform; ‘Flowed’ and ‘Positioned’.

The ‘Flowed’ subforms generally follow the hierarchy represented by the xsd data schema.  The ‘Positioned’ subforms represent physical groupings of fields at the same logical level within the xsd data schema.  A flowed approach will allow the form to work in a dynamic nature. For example, for an invoice you would define one header, one detail line, and one footer.  The data would then be bound and for each line on the invoice a new detail line will be created, and the Reader will then flow all trailing subforms correctly.

□     Variables

There are two types of variable; ‘Variables’ and ‘Script Objects’.

Variables are used for storing any data string.  You can use Javascript to read or write to these variables.  ‘Script Objects’ are (groups of) Javascript sub-routines that can be called at any point using Javascript behind form/field events.

 □     Referenced Objects

These are objects that are not naturally occuring in the form, but may appear based upon certain events.  The classic example of this is a Footer subform that should only appear if a page break occurs on another subform.

 Subform definition and binding

The top-level subform is always FLOWED.

As you work your way logically through the subform then each subform is FLOWED until the final subform in which data fields sit, which is POSITIONED.  Fields must always sit inside POSITIONED subforms if they are to be displayed, as it is not possible to physically position a field inside a FLOWED subform.

It is essential to have this hierarchy of flowed subforms since the option to set a subform to be repeating is only available if the parent subform (the next level up) is FLOWED.  However, it is possible for either a FLOWED or a POSITIONED subform to be repeating as long as the parent subform is FLOWED.

It is not necessary to have a 1:1 match between the subforms in the form and the subforms designed within FLM: The form will often require additional subforms in order to handle the field positions as well as the data flow.

It is not necessary to bind each subform in the data hierarchy, unless the subform has repeating rows or is nested within another subform that has repeating rows. In other cases the binding of the field is sufficient.

Binding for non-repeating subforms.

There is no need to bind non-repeating subforms as all the fields within those subforms are effectively at root level, be they header fields, item headings, footer fields etc.

The binding of the fields inside non-repeating subforms takes the following form:

$record.Header.form_status

In this example ‘Header’ is the data node in the xsd data schema and ‘form_status’ is the field name under the ‘Header’ node in the xsd data schema.  If there were more sub-nodes in the data schema then they would all appear in the binding path.

Binding for repeating subforms.

It is essential to bind subforms that can repeat.

The binding of the subform takes the following form:

 $record.Header.form_status

In this example, ‘EmployeeUtil’ is the data node in the xsd data schema that sits underneath the root (‘DATA’) node.  ‘ResUtilisation’ is the data node in the xsd schema that contains repeating fields. The notation of the [*] means for all nodes that match this Xpath query.

If the repeating subform was defined with a parent of ‘ROOT’ then the binding would take the following form, as no path of the node hierarchy would be necessary:

 $record.ITEM[*]

In this example, of course, the node is called ‘ITEM’ and its parent is the root ‘DATA’ node.

The binding of a repeating subform is different depending on whether there are any nested subforms within the subform to be bound.

If there are no nested subforms then the POSITIONED subform is set to have repeating rows, and is bound to the data node.

If there are further nested subforms within the subform that contain data to be bound, then the FLOWED subform is set to have repeating rows and is bound to the data node.

This often means that there is a POSITIONED subform without binding (ie ‘Normal’ binding) that sits in-between the bound FLOWED subform and the fields within that subform.  This in turn means that the binding for those fields is takes a different form.

Note that there is an option to define a data schema with separate nodes for the repeating subform and for all the fields at the level of repeating subform:

Workorder                                     FLOWED, REPEATING
    Workorder_info                         POSITIONED
        <fields>

          Workorder_details                FLOWED
                Employee_details            POSITIONED, REPEATING
                    <fields>

                   Plant_details                POSITIONED, REPEATING
                    <fields>

In this scenario the subforms ‘Workorder’, ‘Employee_details’ and ‘Plant_details’ must be bound, but it is not necessary to bind the subform ‘Workorder_info’.   (While it is not needed it is best pratice to always bind subforms to the corresponding node.

However, if there is a corresponding data node(ie. There are no data fields are defined under the ‘workorder’ node, just nodes for info, employees and plants) then the Workorder_info subform should be bound, and this means that the binding is the same as for a normal POSITIONED subform regardless that there are nested subforms.

In the scenario where the POSITIONED subform is bound then the binding for fields within a repeating subform takes the form:

 EBELP

The immediate parent of the field defines the full data path so there is no need to define it again. Binding always work on a relative path unless they start with record in which case they become absolute paths.

In the scenario where the FLOWED subform is bound but the child POSITIONED subform is not bound, then the binding for fields within a repeating subform takes the form:

 $record.ITEM[*].EBELP

This is because the immediate parent of the field (the POSITIONED subform) has no binding, so the full data path is required.

Do not attempt to bind both the FLOWED and POSITIONED subforms to the same data node.

Binding for nested subforms.

The binding for nested subforms follows exactly the same pattern as above.  This means that if there are further nested subforms then the FLOWED subform must be bound, otherwise the POSITIONED subform should be bound.

Since nested subforms always sit inside FLOWED subforms that are bound, then the binding of the nested subform is not fully declared, but instead it is just the subform name:

 plantdata[*]

The binding of the fields is the same as described in the previous section.

Note that in all cases the bound subform is the subform that is set to have repeating rows.

Pagination control.

All subforms in the data hierarchy should be set to ‘Allow page breaks within content’ except for the bottom-level positioned subforms where it may be desirable to keep the form fields together.  The ‘allow Page break’ will allow a set of flowing subforms to natural flow over a page and then you can define a trailer (footer) and header subform to be placed on the next page. 
These can include Referenced Subforms.  If you have a group of subforms that you want to bind together then set the Page Break option of and then use the ‘Keep With’ Flag.  An example of this is an invoice line with special details section which could be long text that could span one or more lines.  Therefore running of the Page Break option here and setting the keep with options will ensure if the detail line fits but the special instructions do not it will place both on a new page.

Form Variables.

FLM injects and fills a number of form variables into PDF forms. Some of these are used by FLM when the form is submitted, while others are there for use by the form itself. Some are injected at runtime, while others will allready be on the template if it  is has been generated from the 'Master Template' and will be filled (not injected) by FLM. The values inserted by FLM at runtime overwritte the values allready on the template and these in turn may be overwritten by Javascript on the template. The following table lists all variables inserted/filled by FLM after a 'Form Wizard' run and at runtime:

 

Variable

Description

Filled by form Wizard

Inserted at runtime

Filled at runtime

CCODE

Customer code

X

 

X

FTYPE

Form Type

X

 

X

FLANG

Language

X

 

X

FVER

Version

X

 

X

FID

Form ID

   

X

FID_VAR

Form Variant

   

X

FSTATUS

Form Status

   

X

RET_EMAIL

Sender email address

X

 

X

REC_EMAIL

Email recipient

   

X

RET_FILE_TYPE

Return file type (for offline forms ie PDF or XML)

X

 

X

FTRANSPORT

Form Transport Mechanism (ie Offline, Online via Java Portal, Online via BSP Portal etc)

X

 

X

FILLABLE

Fillable flag

 

X

X

FCURRENTUSER

Current User

 

X

X

STATUS_<STATUS_NAME>

There' ll be more than one of these. It's basically a list of all the statuses configured in the system (together with FLM 'Special Statuses' ie Draft)

 

X

X

ACTION_<ACTION_NAME>

Same as above for actions

 

X

X

COLOUR_<COLOUR NAME>

Same as above for custom colours

 

X

X

TEMPLATE

Template option. The difference between this and the FLANG variable is that FLANG will always contain the 'Template Option' at which the form was originally rendered at, whereas TEMPLATE may change from variant to variant if so set via 'Template' user-exit

 

X

X

PREV_PAGE

Variable used for navigation (it determines the page you navigate to after a render error or a successful submission) in the MultiUI portal.

 

X

X

 

For HTML forms, FLM uses a simillar concept but inserts/fills meta-nodes with the corresponding name, rather than form variables. Bellow is equivalent list for HTML forms:

 

Variable

Description

Filled by form Wizard

Inserted at runtime

Filled at runtime

CCODE

Customer code

X

 

X

FTYPE

Form Type

X

 

X

FLANG

Language

X

 

X

FVER

Version

X

 

X

FID

Form ID

 

X

X

FID_VAR

Form Variant

 

X

X

FSTATUS

Form Status

 

X

X

RET_EMAIL

Sender email address

 

X

X

FTRANSPORT

Form Transport Mechanism (ie Offline, Online via Java Portal, Online via BSP Portal etc)

 

X

X

FILLABLE

Fillable flag

 

X

X

FCURRENTUSER

Current User

 

X

X

STATUS_<STATUS_NAME>

There' ll be more than one of these. It's basically a list of all the statuses configured in the system (together with the FLM 'Special Statuses' ie Draft)

 

X

X

ACTION_<ACTION_NAME>

Same as above for actions

 

X

X

COLOR_<COLOUR NAME>

Same as above for custom colours. For HTML the spelling is 'COLOR' whereas for PDF it's  'COLOUR' I'm afraid...

 

X

X

TEMPLATE

Template option. The difference between this and the FLANG variable is that FLANG will always contain the 'Template Option' at which the form was originally rendered at, whereas TEMPLATE may change from variant to variant if so set via 'Template' user-exit

 

X

X

NEXT_PAGE

Variable used for navigation (it determines the page you navigate to after a render error or a successful submission) in the MultiUI portal. Same as 'PREV_PAGE' for PDFs.

 

X

X

Please note that the above lists only include variables/meta-nodes filled by FLM and that there may be any number of additional variables on a template.