The # symbol used in a date display format for a text input field will render the preceding date part into a dropdown box. For example the date format dd/MMMM#/yyyy will give:
/ January February March April May June July August September October November December /

The Case options set how the case of the data should be changed. The options are Preserve, Lower, Upper, Title and Sentence. Preserve leaves the case exactly the same, Title capitalises the first letter of each word in the string of data, and Sentence capitalises the first letter of the first word. Lower and Upper should be self-explanatory. The Whitespace option specifies how any whitespace entered in the value for this field should be treated. The values are Preserve, which leaves the data as entered, Collapse, which removes whitespace from the beginning and end of the string and then shrinks any group of whitespace characters to a single space, and finally Remove, which removes all whitespace from the entered string. The Calendar Popup section is an option that can be used for fields with a data type of date (see Data Constraints). If the checkbox is ticked, upon generating the page, a link will be created next to the field that will bring up a calendar window from which the user can select the date they require. This option should only really be used for Text Box type controls. The Calendar Type list shows the various selection and display methods for the calendar. These include the ability to navigate monthly or yearly, and to enter a value for the year. The Calendar Display Method option controls whether the displayed calendar will be shown in a completely new window (Popup window) or whether it should look like part of the existing page (In Page Display). The second option is often thought to look better, but may cause problems with older browsers if there are certain control fields (eg select boxes) in the vicinity. The Button Styling option allows a CSS class name to be specified for the calendar display button, that could be used to show a calendar image for example. For the default CSS file provided, the datePickerIcon class name should be used. The Button Text option allows us to specify the caption that should be used for the calendar popup button.

2.3.2.7 Custom Attributes

The Custom Attributes section provides an easy way to add extra attributes into your HTML markup. The section will show all the currently defined custom attributes as well as allowing you to add new ones. For example, using certain Dojo effects would require you to insert certain custom attributes for them to function properly. Please see the Hyfinity FAQ for examples of how to use custom attributes with third party JavaScript libraries such as Dojo.

2.3.2.8 Accessibility Options

The Field Tip field allows the user to input a short description about the field which will be used by screen readers and other browsers Inputting an Access Key will allow shortcut key access to the field. The Tab Index allows the user to specify the order of the tabbing index of the field on the page. This should be a numeric field.

2.3.2.9 Hint and Error Details

This section on the Field Details page provides control over displaying of error and hint information with this field. These options should be considered along with the settings on the Page Details page. The Validation select box allows us to control whether the data entered by the user for this field should be validated or not when the page is submitted. We can either turn this on or off, or set it to be dynamic based on some data binding information. Even if this field is set to be validated, the Validate option on the appropriate submission event must be ticked for the validation to take place. Enabling the Create Message Container check box will create a container beside the field, to contain any error or other messages. This is required for the Local Error Message functionality from the Page Details section to work for this field. Once this has been selected, a Hint can be specified by selecting the Provide Hint checkbox. A hint is a custom message that should help the user know what to enter for this field, or what the information is saying. The two styling boxes allow CSS to be applied to the message container when it is showing the hint, and the Hint Message text area should be used to enter the actual hint message. The Error Display Method setting on the Page Details page will control how the hint is displayed. The Show Server Message checkbox allows you to associate this field with messages from the server. If this is selected, some binding information will need to be provided to set where the message should come from. If this option is selected, and matching data is present in the incoming data, this incoming message will be shown next to the field, overriding any hint that may be specified. Any client side validation errors that occur once the page has loaded will override any server messages or hints specified. The Retain through client side validation checkbox sets what should then be shown after the client side validation problem has been fixed. If ticked, the server message will be re-shown, otherwise the hint or no message will be shown as appropriate. The final two boxes should be used to set how the server message should be styled when it is being shown.

2.3.2.10 Description Details

This final section provides a simple control for entering a description against this field. The user can enter any details they want in this text area to try and aid in understanding the purpose and display of the current field element.

2.3.3 Group Details

The group details page allows us to configure how each group will be displayed in the generated output. This information appears when you select a group on the left hand panel representing the page information. The top of the page displays the short name for the current group so we can ensure we are working on the correct one. As with the Field Settings page, we can click the Show Full Name button to show the full name of the current group. The two styling text boxes allow us to associate CSS classes with this group (Group Styling (Class) text box) or to provide a direct CSS string that should be applied to this group. These can be used for visual styling (e.g. to give the group a coloured background) or to enable the creation of a hierarchical CSS file that can display elements differently based on their position within the hierarchy. The Extended Border Styling option is used to provide more control over the border display of this group. This can be used to show rounded corners, or shadows for example. See the appropriate entry on the WebMaker FAQ for more details on how this is achieved. The Display Method option provides some control over how the group contents will be laid out in the generated page. There are four main options available, which are Vertical, Horizontal, Table and Grid. The remaining option, Horizontal Table should only be used when this group is beneath a repeat as described below. The Grid option is the most flexible of the four, as it gives the user control over how many rows and columns will be displayed, and exactly which components will be present in each 'cell' of the grid. Please see the section on Manipulating the Page Structure for details on how this is specified. There is a special case that occurs if this group is the only child of a repeat element. In this case, if the Display Method of the group is set to Table, the labels will be taken out of the repeat to produce a table with a number of rows based on the data producing the page. This can be useful for displaying summary tables of information. If the Horizontal Table Display Method is chosen, the resultant output will be similar to this turned on its side. This means that the data is controlling the number of columns in the table, with the labels down the left hand side. The Force Table Layout checkbox provides some more control over how the group is generated. Ticking this box will tell the system to use HTML table mark-up to render the group, rather than using more generic container elements such as DIVs and SPANs. This option may also be useful for fixing the relationship between grouped elements in the generated output. Therefore, it may make sense to tick this box for groups at the lowest level, but leave it unchecked for groups higher up in the page hierarchy. The final checkbox - Use a Fieldset for this group, puts the elements in this group within a containing border, thereby separating it from the rest of the page, and making it more easily distinguishable. This option is often recommended for accessibility, as it provides the user with more context information about the fields contained within it. The Label position for contained components option is used to provide control over where the labels will be shown for any fields or groups contained within this group. The default option is to place the labels to the left of each field, but if you wanted to change this (for example to put the labels above or to the right of each field), you could put he fields within a group, and then set this property accordingly. Depending on the Display Method of this group, this setting may not be available, or the options provided may be reduced. The Vertical display method prvoides all the options. Label Details - This section controls whether a label is shown for this group. The format of the controls is the same as for the field label described previously. The checkbox is used to indicate whether the label is required, and the radio buttons decide whether it is a static or dynamic label. If a static label is required it is entered into the Static Label text box, or alternatively binding information must be set on the bindings page to create a dynamic label. The styling options allow full control over how the label will appear using either defined CSS class names, or a valid CSS string.

2.3.3.1 Group Visibility Settings

The Visibility Details section provides a number of options around controlling when this group will be displayed. If a group is hidden, then any components it contains will also be hidden.

The available options are described below.

Display Group Based on the Value of a Field? - This option is used to indicate that this group is dependant upon the value of another field on the page. If ticked, the following two options are required, and only if the given field has the specified value will this group be shown. This process is done on the client side, and as the chosen field's value is changed this group will be visible or hidden as appropriate. Field - This dropdown provides a list of all the fields on the page that are outside of this group. The value of the selected field will be used to control the visibility of this group at runtime. Value - This field should be used to enter the values of the selected field for which this group should be visible. Multiple values can be entered by separating them with semicolon (;) characters. At runtime, as long as the selected field's value is one of the ones entered here, the group will be visible. Hide Group Based on Runtime Server Data? - This option provides an alternative method for conditionally hiding this group. In this case some binding information will need to be specified that specifies when to hide the group. This check happens on the server, so if hidden, the group contents will never be available on the client side. Submit Data if Group Not Visible? - Regardless of which of the two hide modes above are used, this option controls how hiding a group will affect the underlying data. If ticked (the default) then the data will not be affected, but if it is unticked, then any information relating to a currently hidden group will be removed from the underlying data. In order to do this, some binding information will need to be specified so that the data can be inserted back again if the group is re-shown. Disable Group Based on Runtime Server Data? - This option allows you to easily disable all the fields contained within this group in certain situations. Data binding information is used to determine when the fields should be disabled, and the settings against each field control how they will appear when disabled.

Please see the How To Guides on the FAQ, located at for some examples of the use of these options.

2.3.3.2 Group Events

The group events section allows events to be associated with each group. This is achieved by specifying the script to execute when a particular event (e.g. onclick) occurs. FormMaker allows events to be associated with the group itself and its label. The options available for group events are the same as those defined previously for field level events, with the exception being that the URL Location action type can not be used for group events. One example of the use of group level events may be to highlight a row in a data table as you move your mouse over it.

2.3.3.3 Group Custom Attributes

The Custom Attributes section provides an easy way to add extra attributes into your HTML markup. The section will show all the currently defined custom attributes as well as allowing you to add new ones. For example, using certain DOJO effects would require you to insert certain custom attributes for them to function properly.

2.3.4 Repeat Details

The Repeat Details page provides some control over how the contents of the repeat will be presented, including sorting and styling options. Many of these options work best if used on a repeat having one group as a child, which has a display method of Table. These details appear when a Repeat component is selected on the left hand panel representing the page elements. The top of this page provides the full name of the current repeat, and a checkbox that can be used to try and solve display problems that may occur in some browsers. Element Sorting This section controls if and how the elements within this repeat will be sorted at runtime. Ticking the Sort Containing Elements checkbox indicates that the elements should be sorted and so requires some binding information to specify what to sort by. The Sort Order option selects whether the data should be sorted in ascending or descending order, or alternatively can be set to dynamic to enable this option to be pulled in from the data used to construct the page at runtime. In a similar way, the Sort Data-type control can be set to text, number or dynamic. This option sets the type of data to sort and is needed, as for example, 10 would come before 2 if the sort data-type was text. The Assume Default Sorting Behaviour checkbox will cause the system to make some assumptions about the sorting mechanism and the binding information required to try and minimise data entry requirements to achieve this functionality. This will add event handlers for the 'onclick' event to each label and will assume the required binding information. If data is entered for the Sorted Heading Styling text boxes, this will override the styling specified on the field settings page for the label of the element that is currently being sorted. This provides a way for the page to show which element is currently being sorted. Row and Column Styling Both of these sections work in the same way, with one controlling row styling and the other column styling. The aim of these options is to create alternate styling of rows and columns in a table of data by switching between two different sets of styles. The Alternate Styling select box turns this feature on or off, or sets it to dynamic, in which case some runtime data determines whether it should be applied or not. The Change Interval specifies how often the styles should be changed. A value of 1 indicates that the styles will alternate after every row (or column) and so is likely to be the most common option. A value of 2 will create 2 rows (or columns) with the first style, then 2 with the second etc. The styling text boxes allow the CSS class names or text strings for each of the two alternating styles to be specified. If any styling has been applied to the background of elements within this repeat, that will be applied as well as the alternating styles specified here. The Restrict Table Height? option (under 'Advanced Options') can be used to restrict the number of entries within the repeat that are shown at any one time. This will cause vertical scrollbars to be displayed on the screen to allow the user to see all the entries. The Number of rows to display field should be used to specify how many to show. This option is only available for repeats that contain a single group with a 'Display Method' of 'Table'

2.3.5 Custom Details

If a custom field is selected, the Custom Details section will show. Here, the user is free to put in any content that is needed, with the only requirement being that it is valid XHTML. This may be useful for more advanced users, or for more complex data display and management. You will be required to fix any invalid content before navigating away from the page.

2.3.6 Paragraph Details

If a paragraph field is selected, the Paragraph Details section will show. This is used for basic paragraph text entry.

2.4 Data Bindings

FormMaker provides the ability to bind data from the server to the web page elements for prepopulation and also bind page data back to the server after information has been captured or modified on the web page. FormMaker achieves this by using one XML message structure to represent the data on the server before a page is prepopulated and a second set of XML structures, each of which capture the information submitted by each action on a page. You can view the Data Binding information by using the Data Bindings tab. When you have the Bindings tab selected on the left hand panel, you should notice two tabs in the centre. The Page Display Bindings tab will contain the bindings that prepopulate the page using the XML document structure on the right. the second Action Submission Bindings tab will contain a list of actions. As you select each action the submission bindings for the selected action will be revealed, together with the XML document binding structure for this particular action on the right hand side.

2.4.1 XML Binding Structures

XML document structures for data binding When you create pages using the Page Structure tab, FormMaker automatically generates binding structures by default. These XML document structures are created using best assumptions and they can be modified using the Edit or Edit in Editor links on the right hand panel. Please don't forget to use the Refresh Document link to reflect your changes. These document structures fall into two types. The page display documents are used purely to help with generating the bindings, and for previewing the pages. They will not be used by the running application. The action submission documents however will be used at runtime to provide the structure needed to bind the submitted data into. (Unless the 'Use base document structure' option is turned off under Action Configuration.)

The following provides some detail of the decision making processes that are used to generate the XML document structures for data binding:

Standard Palette Controls - When standard palette controls are dropped on to a page a default element using the control name is created within the formData element. Please note that this is the default container for page fields when FormMaker has not been able to establish further binding structure for a given element. The /mvc:eForm/mvc:Control and /mvc:eForm/mvc:Data elements are the generic containers for MVC messages and will be applied to all messages by default. This is to provide a standard wrapper that can be used during development. The same binding structure is generated for Page Display Bindings and Action Submission Bindings. This default structure for the Action Submission Bindings will be used for all actions originating from this page which do not have their own binding structures. See Data Sources later to learn about specific Action Submission Bindings. Composite Palette Controls - When composite palette controls are dropped on to a page an entry for each of the contained standard controls is created within the formData element. Data Sources - When datasource elements are used during page design (W3C Schema, WSDL, Database Schema, Templates, Existing Pages, etc.) FormMaker will detect any elements that may constitute a request structure to a database or web service invocation for example. Based on this it will prompt the designer to select an action (if any actions have been defined in the application map) that may submit the selected information structure that was dragged and dropped onto the page. If an action is selected then a binding fragment that is the same as the element that was dragged will be associated with this action and this structured fragment will be shown when the particular action is selected within the Action Submission Bindings tab during the data binding process.

2.4.2 Binding XPaths

Due to the native XML architecture of Hyfinity's technology, the binding information for each page simply consists of a number of XPaths used within the generated XSL. The following screen shot shows an example of how the binding page may appear upon first entry. The left section of the page contains a representation of the structure of the current page. The right hand section contains a representation of the binding files chosen for this page or associated actions as required. Each page contains a content-specific set of helpful guidelines, and can be shown or hidden as needed. Clicking on the XPath Guidelines will display the relevant help notes; clicking it again will hide them. Depending on how the page has been configured, XPath bindings may be required for the Groups, Repeats or Fields within it. Therefore, the remainder of this page is specific to the currently selected page component and actions. The name of this component is provided, and is highlighted in the page structure representation.

For each component, the bindings are split into two types:

Page Display Bindings - These represent all the details needed to render the page correctly. For example working out which value to prepopulate a control with. Action Submission Bindings - These detail how to insert the information on the page back into XML form when the page is submitted. Different bindings can be provided for each action this page is involved with.

No matter what element is selected, the required XPaths can be typed directly into the appropriate text area. Alternatively we can make use of the instance data files to create our XPaths. Once the required part of the XML instance has been found, if we click and drag it to the appropriate XPath text area, the XPath will be automatically created for us. Regardless of how the XPath has been created, FormMaker will try to 'match' it against the instance document. Any matching elements will be highlighted on the document treeview. You can click on the text showing the number of matches to automatically display the document with the matches highlighted. The red bars on the treeview on the left hand side highlight the page components for which binding information is currently invalid, or still needs to be provided. Once all the required XPaths have been entered for a component, the red bar will disappear from the appropriate entry in the treeview. You will notice that most of the XPaths have already been populated. When you add components to the page on the Page Structure screen, the appropriate bindings will be generated based on whether or not the field came from a data source. You can however adjust these default bindings if required. The main bindings that will not have been pre populated are those for additional features that have been enabled, such as conditional styling or dynamic hiding. In these cases, a message saying 'enter_xpath_here' will be displayed, alerting users to fill in XPath values appropriately. The following pages provide a description of what each required XPath is used for.

2.4.3 Action Configuration

The screenshot below shows the Action Configuration tab on the bindings screen, which allows customisation of how the binding process will work for each action applicable to this page. The left side of the screen provides a list of all the actions that can be submitted from this page. You can click to select an action to work with.

For each action, the following configuration options are available:

Use server-side data binding? - If server side binding is enabled, the form data will be bound to the defined XML structure for this action when the action is submitted. The remaining options below will only appear if server-side binding is ticked. Use base document structure? - This option will use the XML binding structure that has been created by FormMaker (which may have been manually edited subsequently) to bind the submitted data for this action. If this option is turned off, then the only way to provide a structure to bind the data to is via the following two options. Keep previous form data? - This option preserves the formData element between server roundtrips. If this option is enabled on your actions, as you move through pages in the application, the formData section will grow to contain a combined list of data from all the pages that have been visted. Maintain Additional Data - This link enables you to indicate multiple fragments within the XML binding structure that need to preserve their data between server roundtrips. Each fragment matched by an XPath entered here will be taken out of the data available as the page is rendered, and will be reinserted under the mvc:Data element in the document submitted to this action.

When entering Action Submission bindings for any component on the page, these details will be processed to always show the correct binding structure on the right hand side. Set bindings based on another action? - This enables you to set all the bindings xpaths for every component on the page for this action so that they are the same as another action from this page. To do this, you just need to enable this checkbox, and then select which action should be used as the base for the current one. Any changes made to the bindings for this base action will now be automatically applied to this action as well. When using this option, it is important to make sure that the structure configuration options detailed above are set the same for both actions. Multiple Bindings There may be occasions when you need to bind the data from the same page field to multiple locations within the submitted document structure. You can achieve this by using the Add Additional Binding link. This is available when configuring the Action Submission Bindings for any component on the page.

2.4.4 Repeat XPaths

Each Repeat can require a number of XPaths based on the options set in the Repeat Details section. Page Display Bindings

Repeating Data Location - This binding is always required. This sets the context for the repeat, i.e. what elements we are repeating over. Sort Location - If sorting is selected (on the Repeat Details page), this XPath must point to the element that should be sorted against. However, if the default sorting checkbox is selected on the Repeat Details page, this textbox will be disabled. Sort Order Value - If the sort order is set to dynamic, this XPath will be used to determine the ordering. At runtime, this must evaluate to either ascending or descending. As above, this XPath textbox will be disabled if default sorting is enabled. Sort Datatype Value - If the sort data-type is set to dynamic this XPath is required. At runtime, this must evaluate to either text or number. With default sorting, this field will similarly be disabled as in the two above. Alternate Row Style If - If the alternate row styling option is set to dynamic, this is used to determine at runtime whether alternating row styling should be used for this repeat. This XPath will be evaluated to either true or false to make this determination. Alternate Column Style If - If the alternate column styling option is set to dynamic, this is used to determine at runtime whether alternating column styling should be used for this repeat. This XPath will be evaluated to either true or false to make this distinction.

Action Submission Bindings

Repeat Submission Binding - This option sets the context point for this repeat in the data submitted from the page. This should point to the element that is repeated in the data. This binding is only required for repeats that contain editable fields (eg text boxes)

2.4.5 Group XPaths

Each Group can require a number of different bindings depending on the options selected: Page Display Bindings

Hide If - This XPath is used as the check to determine whether to show this group or not. If the XPath evaluates to true at runtime, using the standard XPath rules, the group will then be hidden. This XPath is required if the Hide Group Based on Runtime Data option has been selected (see Group Details). Disable If - This XPath is required if the Disable Group Based On Runtime Data option is selected on the Field Details page. If this XPath evaluates to true at runtime, then all the fields within this group will be disabled. Label Value - This XPath is required if a dynamic label has been requested for this group. The text value of this XPath at runtime will be used for the group label. Set Value Events - If a dynamic Set Value action type is selected for an event against this group or its label on the Group Events section, these XPaths will become available. The resulting value from evaluating each XPath will be put into the target field of the event when the event gets triggered. Dynamic Group Style XPaths - The XPaths in this section are used for setting the dynamic background styling of the field if dynamic background styles have been selected on the Group Details page. The first field, Apply '...' Group Style if, will be used for entering a condition to be fulfilled in order to apply the specified conditional style. If the XPath here evaluates to True, the entered class (on the Group Details screen) will be used for this element. If dynamic was selected, another XPath text area will appear: Dynamic Group Style Value. The value of this XPath will be converted to a string at runtime, which will be used as the CSS class name to apply to this field's background container (if the condition XPath is true). Dynamic Label Style XPaths - These XPaths work in the same way as the XPath values above, except that they define the dynamic styling requirements for this group's label.

Action Submission Bindings

Context Location - This XPath is required if the 'Submit Data if Group Not Visible?' option has been unticked in the Group Visibility Settings section. It is used to indicate the location in the data that contains all the information about this group. Group XML Fragment - This is required if the 'Submit Data if Group Not Visible?' option has been unticked in the Group Visibility Settings section. Unlike the other binding details this field should contain an XML fragment. This fragment should be the empty structure needed to bind all the fields within this group. This fragment will be inserted into the Context Location (if needed) when this group is visible so that all the contained fields can be successfully bound. This field can still be populated by drag and drop from the instance documents. This will cause the XML structure for the selected element and all children to be inserted into the field, rather than the XPath to it. If this group contains any other conditional display groups with the 'Submit Data if Group Not Visible?' flag unset then this fragment should not contain any data related to the nested group, as this will be stored against the subgroup.

2.4.6 Field XPaths

Each Field may require a number of different XPaths based on the options set on the Field Details section. In addition, if the field supports selecting multiple values (eg a multiple checkbox control or a select box with multiple selection enabled) you will also be asked to select the Data Format to use. This controls how the multiple selected values will be stored in the XML data. The two options are CSV String which combines all the selected values into a single comma separated string, and XML Structure which creates a separate element in the XML message for each selected value. Page Display Bindings

Field Value - This is the location of the current value for this field in the instance document that should be displayed on the screen. Please note, if this field is contained within a repeat, and a relative XPath is required, the repeat variables will need to be used for this xpath if this is a select box, radio button or multiple checkbox control with dynamic options. The XPath Guidelines will detail the repeat variables available. This is because the Options Location value used to find the set of options to display will alter the current context point. Label Value - This XPath is required if a dynamic label has been requested for this field. The text value of this XPath at runtime will be used for the label. Options Location - This XPath is required for select box, radio button or multiple checkbox controls that have been set to have dynamic options on the Field Settings page. This XPath should point to the node set that contains all the data to use when creating all the options for the control. Options Data Value - This XPath is used in conjunction with the Options Location to set the value that should be used in the background and returned from the page for each option selected by the Options Location XPath. This XPath should be relative to the Options Location XPath. Options Display Text - This XPath is used in conjunction with the Options Location to set the text that should be displayed on the page for each option selected by the Options Location XPath. This XPath should be relative to the Options Location XPath. Hide If - This XPath is required if the Hide Field Based On Runtime Data option is selected on the Field Details page. If this XPath evaluates to true at runtime, the field will not be output in the resulting page. Disable If - This XPath is required if the Disable Field Based On Runtime Data option is selected on the Field Details page. If this XPath evaluates to true at runtime, the field will be disabled. If this field is also within a group that has the disable option set, then this XPath will override the group disable check for this particular field. Checkbox Value - This XPath is required if the field type is a Single Checkbox with a dynamic value, and is used to set the value for the checkbox field. Validate If - This XPath is used to determine whether the value entered for this field should be validated when the page data is submitted. The entered XPath will need to evaluate to true at runtime for this to occur. Error from Server Value - This XPath is used to specify a server message to show by this field. The Show Server Message option must be selected on the Field Details page for this option to be available. If at runtime, this XPath evaluates to a string, that string will be used as the server message. Set Value Events - If a dynamic Set Value action type is selected for any field or label event on the Events section, these XPaths will become available. The resulting value from evaluating each XPath will be put into the target field of the event when the event gets triggered. Dynamic Background Style XPaths - The XPaths in this section are used for setting the dynamic background styling of the field if dynamic background styles have been selected on the Field Details page. The first field, Apply '...' Background Style if, will be used for entering a condition to be fulfilled in order to apply the specified conditional style. If the XPath here evaluates to True, the entered class (on the Field Details screen) will be used for this element. If dynamic was selected, another XPath text area will appear: Dynamic Background Style Value. The value of this XPath will be converted to a string at runtime, which will be used as the CSS class name to apply to this field's background container (if the condition XPath is true). Dynamic Element Style XPaths - These XPaths are used for setting the dynamic styling to apply to this field's control if this option has been selected on the Field Details page. These options work in exactly the same way as described above for dynamic background styling. Dynamic Disabled Style XPaths - These XPaths work in the same way as the XPath values above, except that they define the dynamic styling requirements for this field control if it is disabled. Dynamic Label Style XPaths - These XPaths work in the same way as the XPath values above, except that they define the dynamic styling requirements for this field's label.

Action Submission Bindings

Field Submission Binding - This XPath provides the location in the action binding structure in which the value for this field should be inserted when the page is submitted and the particular action called. Submission Context Location - This is required for fields that support multiple values, with the Data Format set to XML Structure. This binding should point to the element that will be repeated for each selected value. Field Value Binding - This is required for fields that support multiple values, with the Data Format set to XML Structure. This binding is realtive to the Submission Context Location, and indicates the location within the repeating element where the actual value should be placed. In most cases this value will be left as '.' to indicate that the value should be placed directly into each repeating element.

2.4.7 Namespace Handling

As already explained, all the data binding information is specified using XPaths. This means that handling of namespaces can be important to ensure the correct details are being bound. Fortunately, FormMaker automatically imports all namespace definitions from the specified instance documents, so for the majority of cases you will not have to worry about namespaces at all. Simply drag your fields as needed to create the bindings, or use the the default bindings provided. However, if you find that you would like more control over the namespaces in use, the Namespace Definitions section can be opened to show all the namespaces that are currently defined. This allows you to see which namespaces have been imported from the instance documents, and provides the ability to add new ones and remove existing definitions. When examining the instance documents, there are often namespaces present that do not have a prefix defined. In this case FormMaker generates a prefix of the form ns1, ns2, etc. for each one. If you would like to change this prefix to something more appropriate, you just need to click the Edit button next to the appropriate definition, and the adjust the prefix value accordingly. Once you have made the change, click the Save button to store the new details. This will automatically update any bindings that are using the namespace to include the new prefix. When entering binding information, FormMaker automatically checks the entered details to ensure that the XPaths are valid and that any namespaces have been defined. If any errors are found these will be detailed on the screen, and the red bar will appear on the treeview to indicate that there is a problem with the field. This makes it very easy to find and fix any problems that may occur.

2.5 Generating and Previewing Pages

Once a page has been set up in FormMaker, we need to generate the page to create the output file for use in the final application. This can be done by clicking the Generate Page link at the top of all the screens, or by selecting the page on the Application Map screen and then clicking the Save link in the Page Details. Alternatively, the Generate Application button will generate all the pages as well as prepare the server-side components represented by the action links and the controllers shown on the Application Map diagram. Once a page has been generated, the output file (XSL) will be created in the XSL asset pool within XDE. To be able to easily see how a page will look, FormMaker provides a Preview function that can be used after generating to provide an example of what the page will look like. This works by generating example HTML for each page using the data provided by the 'Page Display' XML document defined for it. These sample HTML pages are then saved into the webapp directory for your project so that they can correctly pick up all the needed resources, such as CSS, JavaScript, and image files. You can use the Preview Page button available at the top of every FormMaker screen to view what this preview looks like at any time. If you make any changes to the page, you will need to perform a generate operation on the page before the preview will reflect these changes. In order for this to work correctly, there are a couple of settings in the Application Defaults section that tell FormMaker where these directories are located. In most cases you will not need to adjust these values, but for more advanced scenarios (such as using the same webapp resources for multiple projects) they can be changed as needed. The Preview Location box should contain the filesystem location of this webapp directory, eg {install dir}\design\repository\{workspace}\mvc\{project}\webapp. The Preview URL box should be used to provide the URL that FormMaker should use to access this web application, eg http://localhost:7070/Preview/{workspace}/mvc/{project}/webapp. Deployment When you are happy that your pages are looking okay in the Preview, you need to deploy the application to see how it actually works when running. FormMaker provides a button at the top of every screen to deploy the application. This deploys all the pages and controller components in your project to the local runtime environment to test and debug using the Test Dashboard discussed elsewhere in the documentation. Once the full application has been deployed at least once, you can make use of the Deploy Page button when you want to quickly test changes to a particular page in the runtime environment. If you have added any additional resources to your page (CSS files, script files, etc) then you will need to do a full application deployment for these to be picked up. Once you are happy that the project is working correctly, the publication options can be used to package up a version for installing on a production server. For more details on deployment and publication options, please see the Project Deployment and Publication section elsewhere in the documentation.

3 Appendix

Sections within the appendix contain supplementary information to the main documentation set.

3.1 Skin Requirements

FormMaker generates XSL files for use within the Hyfinity Morphyc Architecture. For these files, the skin file will be another XSL that will be imported by the generated file.

The output XSL will not perform the full transform, but instead will define the following named templates that should be called from the 'skin' where required

section_title - Contains the name of the page. page_scripts - Contains the 'script' tags for any custom scripts for this page. This should be placed within the head of the HTML page. css_imports - Contains the CSS import statements needed to pull in the required CSS files. This should be placed within the head of the HTML page. section_body - This template contains the main content of the page, starting from the 'form' level. This should be placed within the body of the HTML page.

If an output file already exists when a generation operation is performed, the result is slightly different, in that only the contents of the section_body, css_imports, and page_scripts templates are recreated. All other templates are simply copied from the existing file. This ensures that any new templates created will be retained. In order to use the advanced value conversion, validation, and error highlighting features of FormMaker a number of JavaScript library files must be included by your skin. This should be done at the same point as the call to the page_scripts template is performed. The skin file used in the tutorial examples includes the full list of standard scripts. You can view this list by opening the skin file xsl. In order to use the AJAX based partial page functionality, the Dojo toolkit needs to be imported by the skin. Please see the provided demo_skin.xsl file for an example of this. In order to use the Message Tooltip form of error display, the following HTML fragment should be placed in the skin so that it is created directly under the HTML body tag in the output.

<div id="tipDiv" style="position:absolute; top:-100px; left:-300px; width : 300px; height : 100px; visibility:hidden;">
    <iframe title="tipFrame" id="tipFrame" name="tipFrame" src="#" style="width :300px; height : 100px;">
    </iframe>
    <div id="messageDiv" style="position: absolute; top : 0 ; left : 0; width : 100%; height : auto; background : white; border : thin solid black; padding : 2px;">
    </div>
</div>
                    

In this fragment, all the required styling has been in-lined on the components; however it may be better to separate this out and used named styles instead. The styling applied to the messageDiv will control how the information appears to the user. In this example there will be a white box with a black border containing the text.

3.2 Selecting Files

In order to use FormMaker, a variety of different files need to be chosen. This is achieved using the Repository Viewer application, which provides a simple mechanism for viewing and manipulating files which ensures a consistent approach. An example Repository Viewer window instance is shown below, which will appear upon clicking the Select Skin button from within the Application Map screen in FormMaker. The contents of the first column will depend on the location and function of the button that called up Repository Viewer. This column shows all the categories of documents that are available to view. In the example above, the list shows just one category, XSL, which is the directory where the current project's XSL files are kept. Selecting a category will update the right hand column which shows the list of all the documents in the selected category. The red text indicates the currently selected category. Clicking on any of the displayed documents will close the window, and that selected filename will be passed back to FormMaker to be used and saved as needed.

The functions available for documents within a collection are described below.

Upload - This uploads a file from the local file system which has been selected using the Browse button to the current categroy. The name of the new File will be set by the File Name field. New - This option creates a new file in this category. The name of the new document will be taken from the File Name field. Copy - This option copies an existing document within this collection to a new document with a different name. The file to copy should be selected using the radio buttons, and the new document name entered into the File Name field. Rename - This option renames the selected file. The file to rename should be selected using the radio buttons, and the new name entered into the File Name field. Edit - Opens the document selected by the radio buttons so that it can be easily viewed and editted within the browser. Edit in Editor - Opens the document selected by the radio buttons in an external editor (eg XMLSpy) so that it can be edited directly. Delete - This deletes the document with the selected radio button. This option cannot be undone, so should be used with caution.

By default, the application will try and use Altova's XMLSpy as the external editor for the Edit in Editor command. When a document has been opened in an external editor, it can be saved directly within the editor to update the version stored in the repository. You will have been given the option of changing the editor to use during install time, but this can still be changed at a later point if needed. For details on this please see this entry on the FAQ.