hyf.editabletable.init(hyf.editabletable.getLastTableOutput(), {
                    validate:true,
                    ...
                    messages: {
                        insertBtn: 'Add New Row',
                        insertBtnTitle: 'Click to add a new row of data to the table'
                    }
                });
                

hyf.pagingtable.init(hyf.pagingtable.getLastTableOutput(),
{
    enablePaging:true,
    tablesorterOptions: {
            widthFixed:true,
            widgets: ['zebra', 'stickyHeaders', 'filter']
    },
    pagerOptions: {
            ...
    }
}
);
                

<script type="text/javascript">
/* For more details on the available configuration options please see the following FAQ entry:
* http://www.hyfinity.net/faq/index/solution_id/2005
*/
<xsl:text disable-output-escaping="yes" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    hyf.pagingtable.init(hyf.pagingtable.getLastTableOutput(),
        {
            enablePaging:true,
            tablesorterOptions: {
                widthFixed:false,
                widgets: ['zebra']
            },
            pagerOptions: {
                size:null,
                processAjaxOnInit: false,
                ajaxObject: {
                    dataType: 'html'
                },
                ajaxUrl: 'PARTIAL_PAGE_ACTION_NAME.do?page_number={page}&amp;page_size={size}&amp;{sortList:sortcol}',
                ajaxProcessing: function(data, table, xhr) {

                    var $data = $(data)

                    return {total: $data.find('#total').val(),
                            rows: $data.find('table&gt;tbody&gt;tr')
                           };

                }
            }
        }
    );
</xsl:text>
</script>
                

<fileUpload success="true" name="myfile.png" type="image/png">base 64 encoded string</fileUpload>

<fileUpload success="true" name="myfile.png" type="image/png" location="c:\path\to\webapp\uploaded_files\01715441E103CDE532226B1C35826E17_myfile.png"/>

<menu id="header_menu" xmlns="http://www.hyfinity.com/mvc">
<item hint="Link to Home Page" id="home" value="Home">
    <event action="http://www.hyfinity.com" name="href" />
</item>
<item hint="Link to Products Page" id="products" value="Products">
    <event action="http://www.hyfinity.com/#products" name="href" />
</item>
<item hint="Contact Details" id="contact" value="Contact">
    <event action="alert('Send us an email!');" name="onclick" />
</item>

</menu>

<menu id="header_menu" xmlns="http://www.hyfinity.com/mvc">
<item hint="Main Menu with Sub Menu of Options" id="item1" value="Main Menu">
    <menu>
        <item hint="Home Page" id="home" value="Home">
            <event action="http://www.hyfinity.com" name="href" />
        </item>
        <item hint="About Message" id="about" value="About">
            <event action="alert('Hyfinity Limited');" name="onclick" />
        </item>
        <separator />
        <item hint="Link to Products" id="products" value="Products">
            <event action="http://www.hyfinity.com/#products" name="href" />
        </item>
        <item hint="Link to Downloads" id="downloads" value="Downloads">
            <event action="http://www.hyfinity.com/#downloads" name="href" />
        </item>
        <separator />
        <item hint="Sub Menu of Further Options" id="" value="Sub Menu">
            <menu>
                <item hint="Link to Community" id="community" value="Community">
                    <event action="http://www.hyfinity.com/#community" name="href" />
                </item>
                <item hint="Link to Support" id="support" value="Support">
                    <event action="http://www.hyfinity.com/#support" name="href" />
                </item>
                <separator />
                <item hint="Link to Contact" id="contact" value="Contact">
                    <event action="http://www.hyfinity.com/#contact" name="href" />
                </item>
            </menu>
        </item>
    </menu>
</item>
<item id="item2" value="Second Menu">
    <menu>
        <item id="option1" value="Log In" />
        <item id="option2" value="Register" />
    </menu>
</item>
</menu>

It is also possible to create Page Functions from sets of existing event actions. When you hover over events, a Convert to Function link appears in the top right, within the container of the hovered event. This link can be used to create a new page function, containing all the existing actions. The actions will be replaced with a single call to the newly created function.

Display Variables

Please see definition in the previous section.

6.3 Group Events

The group events section allows events to be associated with each group. This is achieved by specifying the actions to execute when a particular event (e.g. onclick) occurs. The Page Designer 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 cannot be used for group events.

7 Bindings Tabs

WebMaker provides Page Display Bindings, for binding runtime server data to page controls. It also provides capabilities for binding page data back to the server after information has been captured or modified on web pages using Action Submission Bindings (Requires server controllers). This is done by using one XML message structure to represent the data sent from the server to the page (INPUT data to Page), and a second set of XML message structures, each of which captures the information to be submitted by each action on a page back to the server (OUTPUT data from Page). You can view the data Bindings information by using the Bindings tabs. The Action Submission Bindings, within the second Bindings tab, contain a list of actions that can be activated from the Page. Each of these entries can be clicked to reveal the submission bindings and the associated XML document structure that will be used to submit data to the server.

Binding Document Structures

When you create pages using the Page Designer, WebMaker automatically generates XML document structures, which are shown in the tree on the right hand side of each of the Bindings tabs. These XML document structures are created using best assumptions and they can be modified using the Edit Document link on the right hand panel. Depending on your Edit | Preferences menu option settings, this will either open the document within an editor in your browser or an external editor. Note: Please don't forget to use the Refresh link to reflect any changes to the binding documents. The Page Display Bindings document is used at design time for previewing pages with sample data, contained within such documents. They are not used by the running application, but the data and document structures prepared by server controllers need to adhere to the same structure to ensure proper rendering of pages. The Action Submission document structures within the second Bindings tab, are used at runtime, to capture and submit information to the server. Many configuration options are available for fine-tuning and configuring the arrangement and behaviour of these binding documents, which will be discussed in more detail later in this section.

The following provides an overview of the decision making processes, used to generate the XML document structures for data binding:

Palette Controls - When palette controls are dropped on to the canvas, one or more elements using the control name or its derivative are created within the formData element. This is the default container for page fields when the Page Designer has been unable to establish a binding structure for a given element. The /mvc:eForm/mvc:Control and /mvc:eForm/mvc:Data elements are the generic containers for WebMaker data and will be applied to all messages by default. This is to provide a standard wrapper that can be used during development. The Control block is mainly used by WebMaker to control the application processing, and the Data block is for the application data. The /mvc:eForm/mvc:Data/mvc:formData is nested within the Data block. The same binding structure is generated for Page Display Bindings and Action Submission Bindings. This default structure for the Action Submission Bindings is used for all actions originating from pages, which do not have their own binding structures. Further detail is available later in this section. Data Sources - When Data Source elements are used during page design (W3C Schema, WSDL, SQL Database Schema, etc.) the structure of the data source is used to create the XML binding structures. WebMaker will attempt to detect if the fields originate from an editable data source. If the source is editable, WebMaker will use a wizard (Requires server controllers) to request additional mapping information between page actions and the target data sources, which will receive the data submitted by such actions at runtime via server controllers. For each action that is selected in this wizard, the structure for the data source, used to design the page, will be added to the submission binding document for that action. If an action is not selected (or if the data source is not deemed editable) then elements will be created within formData as normal. Submission data structures, derived from data sources, will be placed within the /mvc:eForm/mvc:Data element. For web services, this will be the root element of data defined as the Request or Response message as appropriate e.g. /mvc:eForm/mvc:Data/demo:ListContactsRequest or /mvc:eForm/mvc:Data/demo:ListContactsResponse. For SQL Databases, it will be the name of the SQL table selected e.g. /mvc:eForm/mvc:Data/accounts_table When you work with these documents and XPaths, it is important to be aware of namespaces, which is detailed in later sections. Skin Data - Page Display Bindings for Skin Data is handled in the same manner as normal pages. An mvc:skinData fragment is used within mvc:Data to submit skin data for all submissions using a similar structure to mvc:formData. For Partial Pages, you will see a combined list of actions, which includes actions originating from the partial page and also its main parent container page. The XML message structure will be a composite of the data within the main page and the partial pages it contains.

Using XPath to match binding data

The binding information for each page consists of a number of XPaths. XPath is a simple, but powerful document inspection language to match elements inside XML document structures. XPath Guidelines under different areas within the Bindings tabs provide additional information. You can drag elements from the tree structure and drop them on the XPath fields to create XPaths. You can also manually enter XPaths. A Guide to Useful XPath Queries (PDF) on the WebMaker Forum is a useful resource. Most of the bindings will be pre-populated for you. The main bindings that will not have been pre-populated are those for additional features that have been enabled, such as Conditional Styling or Visibility Details selected on the Properties tab. In these cases, a message stating enter_xpath_here will be displayed.

7.1 Field Bindings

Each Field may require a number of different XPaths, based on the options set on the Properties tab. In addition, if a field supports the selection of multiple values (e.g. a multiple checkbox control or a select box with multiple selection enabled) you will also be requested to select the Data Format to use. This controls how the 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 element to be matched against the tree, or XML Structure which needs a separate element in the XML message tree for each selected value. Note: The appropriate option will depend on the data you need to send to the server.

Page Display Bindings

Field Value - This is the location of the current value for a field in the xml document structure that should be displayed on the screen. Please note, if a 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 section will detail the available repeat variables. This is because the Options Location value, used to find the set of options to display, will alter the current context point where the XPath matching starts from. Label Value - This XPath is required if a dynamic label has been requested for a 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. This XPath should match the data to isolate the options for the control. This will usually be a repeating structure in the XML document structure. ... Options Data Value - This XPath is used in conjunction with the Options Location above 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. The element matched is usually a coded value that is stored in the underlying data, but not normally a value that is displayed. ... Options Display Text - This XPath is used in conjunction with the Options Location above 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. These two fields are the equivalent of the static Enumerations found on the Properties Tab, but the data is sourced from the XML document structure and the data will likely have originated from a Data Source such as a SQL Database. Remove If - This XPath is required if the Remove field based on server data option is selected on the Properties tab. If this XPath evaluates to true at runtime, the field will not be sent or output on the resulting page. Disable If - This XPath is required if the Disable field based on Server data option is selected on the Properties tab. 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. This setting can be found on the Properties Tab in the Hint and Error Options section. The field is Perform Client Side Validation on this Field? set to dynamic. 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 Properties tab for this option to be available. If at runtime, this XPath evaluates to a string, that string will be used as the server message. Dynamic Events - A number of event-related XPaths may be required if this field has dynamic event settings. A new XPath will be required for any event parameter defined for this field (whether against the field or its label) that has a based on server data setting. At runtime, the string value from evaluating each XPath will be used in the event processing where needed when the event is triggered. Dynamic Background Styles - The XPaths in this section are used for setting the dynamic background styling for controls, if conditional background styles have been selected against Control Styling within the Properties tab. The first field, Apply '...' Background Style if, is used for entering a condition to be fulfilled in order to apply the specified style. If the XPath evaluates to true, the entered class (within Control Styling under the Properties tab) will be used for this element. If dynamic was selected, another XPath 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 the field's background container (if the condition XPath is true). Dynamic Control Styles - These XPaths are used for setting the styling information for controls dynamically, if this option has been selected on the Control Properties tab. These options work in a similar manner to that described for dynamic background styling, above. Dynamic Disabled Style - These XPaths work in a similar manner to the XPath values above, except that they define the dynamic styling information for disabled controls. Dynamic Label Style - These XPaths work in a similar manner to the XPath values above, except that they define the dynamic styling information for labels.

Action Submission Bindings (Requires server controllers)

Field Submission Binding - This XPath identifies the location within the XML submission document structure where the value of a field should be inserted when the page is submitted for a selected action. 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 relative to the Submission Context Location above, and indicates the location within the repeating element where the actual value should be placed. In most cases this value will be left as . (meaning this element) to indicate that the value should be placed directly into each repeating element.

Multiple Bindings - Add Additional Binding

There may be occasions when you need to bind the data from the same page field to multiple locations within the submitted document structure. For example, you may need to bind the data to a SQL table to update a value, but you also need to bind it to a Web Service call to perform some operation. You can define multiple bindings this by using the Add Additional Binding link

Binding Mode

At the bottom of the Action Submission bindings section you will also see some information indicating whether this particular action is using a Default or Advanced Binding Mode. This determines how the document structure, that will be submitted for this action, is created. This is discussed in more detail in later sections.

7.2 Group Bindings

Each Group may require several bindings depending on the selected options:

Page Display Bindings

Remove If - This XPath is used as the check to determine whether to show a group or not. If the XPath evaluates to true at runtime, the contents of the group will be removed from the HTML page. This XPath is required if the Remove group based on server data option has been selected in the Properties tab. Disable If - This XPath is required if the Disable group based on Server data option is selected on the Properties tab. If this XPath evaluates to true, then all 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. Dynamic Events - As for fields, if a group contains event definitions that use the 'Based on server data' setting, then a binding XPath will be required for each setting. The resulting value after evaluating each XPath will be used in the event processing where required when the relevant event is triggered. Dynamic Group Style XPaths - The XPaths in this section are used for setting the dynamic background styling of fields if conditional background styles have been selected on the Properties tab. 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 Properties tab will be used for this element. If dynamic was selected, another XPath 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 the field's background container (if the condition XPath is true). Dynamic Label Style XPaths - These XPaths work in a similar manner to that of the XPath values above, except they define the dynamic styling information for group labels.

Action Submission Bindings

Context Location - This XPath is required if the Submit Data if Group Not Visible? option has been unticked in the Properties tab. It is used to indicate the location in the data that contains all 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 required to bind all the fields within this group. This fragment will be inserted into the Context Location (if required) when this group is visible, to ensure all the contained fields can be successfully bound. Note: This field can still be populated by drag and drop from the xml document structure on the right. 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 because this will be stored against the subgroup.

7.3 Repeat Bindings

Each Repeat may require a number of XPaths, depending on the options that are set within 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 are being repeated over, which is usually a parent element (container) to the data values used below. Sort element within Repeating Data Location - If Element Sorting has been selected, this XPath must point to the element that should be sorted against. These settings can be found on the Properties Tab Element Sorting Section, when the Sort contained elements? is ticked. 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 ascending or descending. As above, this XPath will be disabled if default sorting is enabled. These settings can be found on the Properties Tab Element Sorting Section, when the Sort Order is set to dynamic. Sort Data-type Value - If the sort data-type is set to dynamic this XPath is required. At runtime, this must evaluate to text or number. With default sorting, this field will be disabled, similar to the above. These settings can be found on the Properties Tab Element Sorting Section, when the Sort Data-type is set to dynamic. Alternate Row Style If - If the alternate row styling option is set to dynamic, this XPath is used to determine whether alternating row styling should be used for this repeat. This XPath will be evaluated to true or false to make this determination. Alternate Column Style If - If the alternate column styling option is set to dynamic, this XPath is used to determine whether alternating column styling should be used for this repeat. This XPath will be evaluated to true or false to make this distinction.

Action Submission Bindings

Repeat Submission Binding - This option sets the context point for repeats in the data submitted from pages. This binding is only required for repeats that contain editable fields (e.g. text boxes)

7.4 Advanced Binding Modes

The Binding Mode determines the structure of the XML data that is submitted for different actions. There are three different modes: Default, Advanced and None. You can configure which mode is used for each action by using the settings within the Advanced Binding Modes section.

None - No data binding will be performed. This mode is selected by unticking the Use server-side data binding? option. Default - This is the default binding mode, and is selected by ticking the Use server-side data binding? and Use base document structure? options only. In this mode, the static XML structure is submitted as shown. This structure is automatically updated as new controls are added. Advanced - Selection of any other options results in Advanced mode. For example, Advanced mode is used if the Maintain Additional Data XPath is provided.

The available options are described in more detail below:

Use server-side data binding? - If server side binding is enabled, the form data will be bound to the defined XML message structure when the action is submitted. If this option is not selected then any submitted data is placed within a flat list of fields in the XML message structure. Fields that cannot be bound or have not been bound to the XML structure, will end up as a flat list of fields. The remaining options below only appear if server-side binding is ticked, which is the default. Set bindings and structure based on another action? - This option allows you to duplicate the action submission bindings for this page across different actions. This enables you to set all the bindings XPaths for every control, based on the settings for another action. This setting will also ensure that the binding document message structure is also exactly the same for all the actions. To do this, you just need to tick this checkbox, and then select which action should be used as the base for the current one. Any changes made to the bindings for the base action will be automatically applied to this action as well. The XPaths are disabled if you are not viewing the appropriate base action. This option can be useful when you have a number of actions that always need to bind to the same submission document structure. For example, sometimes the 'Create' and 'Update' actions may share the same structure. If a particular action is designated as the base for other actions, you will not be able to select this option for this particular action. Use base document structure? - This is the default option and defines the XML structure that is used to submit data for the selected action. At runtime, this structure is populated with the actual values of each of the fields, using the defined binding information for each field. In most cases you will know the structure of information that needs to be submitted at design time. As a result, you can use the default setting to use the base document structure. As you add fields to your page, the content of this base document will be updated accordingly to ensure it contains submission elements for your new fields. You can use the base document structure in conjunction with Keep previous form data and Maintain Additional data settings, to handle significantly more complex binding requirements. Using these options, you can dynamically include additional information to the contents of the base submission document to alter the structure of the submitted document at runtime. Also, if you are only interested in binding to a dynamic data structure, the structure of which will be determined at runtime, then the Use base document structure option can be unticked, and the Maintain additional data option used instead. In this case the contents of the base document will not be used during submission. Keep previous form data? - This option preserves the formData element between server round-trips. If this option is enabled, 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 visited. Form data is any information that is contained within the formData element within the Data section of the message. This will be the case for any fields that have been added to the page that did not originate from a Data Source. This will often be used when you have a form split across several pages. At the end of the last page, the formData element will contain all the information collected across all the pages. Maintain Additional Data - This setting enables you to indicate multiple fragments within the XML structure that need to preserve their data between server round-trips. Each fragment matched by an XPath will be taken out of the data structure as the page is rendered, and will be re-inserted under the Data element in the document that is submitted as a result of this action.

If you use the Maintain Additional Data option, the binding document will switch to show the INPUT data to page document, to enable you to drag and drop the required XPaths. When you return to entering submission bindings, all these settings will be processed to make sure the document structure you see on the right matches the structure that will be submitted. This could include a combination of sections from the base document, and those maintained from the 'data to page' information. To return to configuring the submission bindings either press the OK button at the bottom, or use the Advanced Binding Modes toggle icon at the top.

7.5 Namespaces

A namespace is an important concept for XML documents. Namespaces enable the grouping and identification of elements within XML documents. This makes it possible to have two elements with the same name within different namespaces and ensures they are identified as unique. As namespaces are often long URIs, used to uniquely identify them, XML uses something called a namespace prefix, which is shorthand for identifying the namespace in Documents and XPath queries. You will often see XPath queries with namespace prefixes against XML elements. Generally you will have at least the mvc: prefix (full namespace URI = http://www.hyfinity.com/mvc) defined, as this is used within the default eForm document structure for the data. Note: For brevity, often, the XML document structures shown within the Bindings tab only show the element names. However, when you drag and drop elements the namespace prefixes are automatically applied. Please note, namespaces are not mandatory and it is possible to have elements that do not belong to particular namespaces. In such cases, your XPaths may have namespace prefixes for some elements and not others. WebMaker automatically imports all namespace definitions from XML documents you use in your application, which means you will not have to worry about namespaces and prefix set-up in most cases. Simply drag your fields as needed to create the bindings, or use the default bindings provided. If you do need more control over the namespaces used in your application, then the Namespace Definitions section displays the namespaces that are currently defined. You can modify these definitions to suit your requirements. When XML documents are parsed, not all namespaces will have prefixes defined. WebMaker generates prefixes of the form ns1, ns2, etc. for each namespace that it encounters. You can change these prefixes to suit your requirements.

8 Themes - SASS and CSS Styling

From WebMaker 9.5 you have access to the Theme Designer. The Theme Designer builds on WebMaker's support for SASS and provides an intuitive environment that enables you to create and manage modern themes and colour schemes. The Designer provides intelligent colour-mapping features to assist you with the creation of complete and harmonious colour schemes by simply manipulating a couple of swatches. You can also adjust many other parameters, including landing images, background images, fonts, sizing, borders, backgrounds, transparencies, etc. You can clone and adapt the WebMaker system themes to create your own collection of themes very quickly. You can also switch themes at the click of a button and still have access to the complete underlying SASS files if you require more advanced and low-level control over your applications look-and-feel. You can launch the Theme Designer by using the paintbrush icon on the main toolbar or by using the Design | Theme Editor menu item.

Introducing the Theme Designer

The Theme Designer contains three main panels. The left hand panel contains theme parameters that can be used to change the look-and-feel of the theme that is currently selected and editable. The selected theme is shown on the central preview panel. This panel contains a template html page, with various controls, and is used to provide an illustration of what the selected theme and any modifications to that theme may look like. The third panel on the right hand side shows the theme you have currently selected to be editable and applied to your app. You must select a theme to be current (designated as being used by your app) before you can make it editable and adjust any parameters using the left hand panel. The second collection of theme tiles on the right hand panel shows the system themes that are available for selection. The third collection shows themes that have been cloned and adjusted by you.

Colour Palettes

The left hand panel contains three section of colour tiles, that are related.

Primary Inspiration Colours - These two colour tiles represent the primary, inspiration colours for the theme. Any changes to these tiles will cascade down to the palette colours for element groupings and the override colours for individual elements in the next two sections of colour tiles. The colours will cascade down unless specifically overridden in those sections. Override colours for Element Groupings - The tiles in this section represent the full colour palette used by the theme and each tile may represent the colour for a group of elements on the page. These colours are derived from the inspiration colours and will cascade down to the next section of tiles for individual elements unless specifically overridden in that section. Override colours for individual elements - These tiles are derived from the colour sections above, unless specifically overridden, and typically provide the colour for individual elements. The tiles in this section will typically reference a colour within the pallete section above.

Selecting and Overriding Colours

Each colour tile will display the name of the variable in the underlying SASS file (please see later for more info on SASS). The tile also provides a brief description about its application to the various elements within your app. When you hover over each tile, you should see the colour (or variable that derives a colour) that is currently selected for the tile. You can use the paintbrush icon to change the colour and its transparency. If you override the colour settings within a dependent colour tile, you will see a broken link symbol. This indicates that any changes to 'parent' tiles will no longer cascade down to this tile. You can remove this override setting by clicking the broken link icon. The system themes have been designed with related variables that aim to harmonise colours and simplify the theme creation process and minimise effort for future changes. You should therefore be able to work 'top-down' in you colour selections to clone new themes quickly. You can easily see these cascading relationships by observing the preview pane and the colour tiles as you make changes. You can also view the SASS file to see the relationships between then various colours.

Fonts Icons Sizing Etc

You can use the section on Fonts and Icons to adjust the sizes of fonts, icons, etc. You can also select fonts to append to the font-family selector for the theme. Please note that this element only adjusts the font-family attribute within the underlying SASS file and you will need to ensure that the fonts actually exist for any selected font names or font name you manually enter within the font selector.

Images and Filters

By default, each theme can utilise two images and a filter. There is a background image and a landing (panel) image, which can be changed. If an image is not required, simply enter 'none'. The filter colour is inserted above the landing image and it's colour and opacity can be adjusted to contrast with the foreground as required. Please note - As you make changes to your page in the Page Designer, the elements that are referenced by various selectors (for example, selectors that apply images and filters) need to exist for any changes to take effect. Therefore, changes that are illustrated in the preview panel in the middle of the Theme Designer may not necessarily be reflected in your page designer after you save your changes and exit the Theme Designer.

Editing the SASS File

The SASS parameters on this side panel can be used to alter and fine-tune your theme to your preferences. WebMaker utilises SASS variables within the underlying SASS file and compiles this to produce your theme. If you need greater control over your theme, you can edit the SASS file itself. If you do change the file then please read the guidance information at the top of the file. If you need to revert the whole theme and start again, you can always set any suitable theme on the themes panel to be current and editable. Important - The Files tab in the Page Designer that displays the CSS files used within your app still exists and lists the CSS files. These files should now be listed in a slightly dimmer colour and are produced by the SASS compiler. You can still view and edit these files, but please be aware the Theme Designer makes changes to the SASS file, which is then compiled to produce the CSS files. It is likely therefore that you will lose any changes you make manually to these files. You should therefore make changes to the look-and-feel of your application using the The Designer wherever possible.

Previewing, Cloning and Editing Themes

When you hover over theme tiles on the right hand side panel, you should see options to preview, clone or set the theme to be current and editable. You can preview themes before selecting them to be current and editable. When you select the preview option, the selected theme will be loaded onto the preview panel and its parameters should also be loaded onto the left hand panel. The current theme tile should also shrink in size to illustrate that the preview and parameters are for the selected theme rather than those of the current theme. You can use the preview option to see the look-and-feel of the theme in detail in the preview panel and also view the parameters, but you cannot edit these paramters until you make the theme current and editable.

Upgrading applications using older themes

If you open an application that uses themes in older formats (pre 9.5), the Theme Designer will highlight this fact and also provide instructions on how to upgrade your application to use on of the mode modern theme layouts. You can simply select one of the existing theme tiles to be current and editable. Important - Please note that selecting a theme to be current and editable overwrites your current theme. You should therefore ensure you clone your existing theme by using the Theme Designer or make a copy of your theme from the file system (see later).

Themes Directory Structure

WebMaker 8 made it easier to create and manage new themes. All CSS information for the core web application was contained within a single file called theme.css. Within the application's .../webapp directory there was a collection of theme directories. Each of these directories contained all the styling and graphical assets required by a particular theme. Some themes may have had additional theme css files within the css sub-directory for theme-specific aspects. From WebMaker 9.5 onwards the .../webapp directory for the app will only contain the theme that is current and editable and all theme assets, including the theme.sass file, are located within a theme subdirectory. The collection of user-defined themes are located within .../users/user1/user-resources/themes.

Control Structure

WebMaker version 8.0 introduced a more consistent class-based approach to styling your web applications. Wherever possible, each control is identified by a unique CSS class name. In WebMaker, the HTML markup for a control may change depending on the placement of controls within different containers. This class-based approach enables controls to be identified more easily and consistently. Generally, all styling rules are contained within the top-level class that identifies the control. This reduces the risk of "contaminating" other controls when adjustments are made to specific controls. WebMaker controls are now "richer" by default. Each control is made up of multiple layers of HTML markup, with the class names identifying the relevant parts of each control.

Some of the important layers are detailed below:

{control_name}Control Class - Where control_name is the name of your control, textboxControl for example. controlBody Class - Each control contains a controlBody class that is used for different purposes depending on the type of control. For example, in some instances it might be used for introducing padding and in other instances it might be used to position other control elements within the internal space of the control container.

Within the controlBody, there may be a range of classes depending on the usage scenario and type of control being used. There are some common classes that apply for most controls and these important classes are discussed in more detail below:

Main Control Classes

isMandatory, mandatory Mandatory controls will contain the isMandatory class. In addition, a separate mandatory class will be present for the part of the HTML markup that manages the display attributes of the mandatory marker. isDisabled Disabled controls are indicated by the presence of the isDisabled class. This class is also present for the labelControl, to provide a disabled "look-and-feel" for the control and its associated label. hasPlaceholder, placeholderIcon, placeholderRight WebMaker 8.0 also introduced the concept of placeholder icons. This provides the ability to place an image to the left or right hand side of controls. You simply have to tick to indicate that a placeholder is required and then indicate whether you want the placeholder icon on the left or right hand side of the control. If a placeholder icon is required then a class of hasPlaceholder will appear within the control. In addition, a placeholderIcon class will be added to provide the main styling information for the selected placeholder. The placeholderIcon class is then supplemented by specific placeholder classes to enable you to choose an icon of your choice.

A predefined list of icons is provided, which include the following:

.defaultIcon .validateIcon .searchIcon .dialogIcon .dateIcon .lockIcon .userIcon .emailIcon .phoneIcon .addressIcon

See below for details on how to extend this list of icons. By default, the placeholder icon is placed on the left, but you can also choose to place this on the right. If the icon appears on the right then an additional class placeholderRight will be present within the control markup. hasFeedback, FeedbackIcon WebMaker controls now indicate the outcome of certain operations via a feedback mechanism. For example, server errors and validation errors raise CSS classes hasError and hasSuccess depending on the outcome. These classes are supplemented by 'feeback icon' classes fiError and fiSuccess that provide styling information for the appropriate icons or other attributes to visually portray the outcome of certain operations.

Font Icons

Within each "theme" css directory you can find a theme_icons.css file, which contains a very extensive set of font based icon classes. If the css file is added to the Application, then any of the defined classes can be used for placeholders and other uses. All the classes are prefixed as icon-... e.g. icon-lock-open. There are over 250+ classes that can be used in addition to the standard classes that may be defined in the selected theme files.

Theme Examples

A number of themes are shipped with WebMaker, with some using different approaches for handling the look-and-feel, as well as the HCI aspects of resulting applications For example, the transitions theme does not present hasSuccess styling as they are not defined within the CSS. If a field is defined as mandatory the isMandatory class places a grey triangle over the control rather than a default '*' to the right of the control label. The hasError is rendered with a red triangle over the corner of the control. Most of the other themes display both errors and successfully validated input fields with the display of a cross or tick respectively. You search for the .hasSuccess and .fiSuccess css selectors in the theme SASS/CSS files to gain a better understanding of how this is achieved.

Reduced Images - font glyphs

The new themes in WebMaker reduce the need for image files to enable easier management and production of new themes. This means you will only have to change a single theme.css file in many cases to create very different themes.

Below is a list of the main top-level control classes in WebMaker. Some composite controls are composed from a collection of primitives and may not have a containing class:

.labelControl .textboxControl .outputControl .buttonControl .enhancedButtonControl .hyperlinkControl .radioControl .selectControl .multiSelectControl .filteringSelectControl .autocompleteControl .checkboxControl .switchControl .multiCheckboxControl .dateControl .splitDateControl .currencyControl .numberControl .spinnerControl .textareaControl .richTextEditorControl .paragraph .secretControl .imageControl .customControl .borderedGroup .fieldsetGroup .tabContainer .collapsibleSection .dijitDialog .divider .separator .accordionContainer .basicTableContainer .editableTableContainer .pagingTableContainer .dataCard .chartGroup .mapCanvas .numberSliderControl .treeControl .listBuilderControl

Locating controls based on theme attributes

If you review the theme.sass or theme.css file for one of the predefined WebMaker themes, you should notice the styling rules are arranged around theme attributes. This should enable you to make changes to theme elements such as colours, fonts group heading, etc. in a few locations and have them applied across your application automatically. For example, you will see rules organised under headings such as Group Headings, Labels, Controls, Borders and Margins, etc. If you wish to deal with a single control then you should be able to search for the CSS class that is the primary class for that control and see all the styling rules that apply to this class. For example, if you want to make changes to the textboxControl then search for ".textboxControl" and make changes to the resulting classes. Many of the controls will re-use the same attribute settings, so be mindful when making changes for one type of control. You can learn more about these controls within the Design Palette section.

Additional Notes - Third Party Controls

WebMaker utilises some third party controls in certain scenarios. Examples of this include the Dojo Currency, Number and Number Spinner controls. As a result, you may notice certain "structural classes" with !important against them. These are present to reset or block certain dojo styles that might "leak" through, but may not appear to provide any useful styling functionality in the theme itself. You should also notice the sparing use of the !important attribute to prevent multiple overrides, reducing complexity. You should also notice sparing use of styling classes against HTML elements to reduce the unintended cascading and "leaking" of some of the styling information. Usual cascading is restricted wherever possible within the general classes that might apply to multiple controls. Sometimes you may not observe any changes on the control when certain styles are applied. This is usually be due to the fact that certain style information in the underlying CSS files is overriding the in-line style being applied by the selected option on the Control Styling palette. In these scenarios you will have to track the CSS rules that are being applied and overridden and change your style combinations accordingly. Browser Developer Tools can assist with introspection in such scenarios.

9 JavaScript APIs

Table - The following WebMaker Script APIs are used by the built-in Visibility and Events management processing in WebMaker. You can use these APIs if you need to customise and include additional functionality for your applications:

Function	Parameters/Returns and Notes
Get and Set Fields
hyf.util.getFieldValue(fieldName, getDisplayValue);	Attempts to get the current value for the given field. This will attempt to determine the type of the given field name, by checking dojo widgets, any form elements, and display only containers with the given control id.
	fieldName - The name of the field to get the value for.
	getDisplayValue (Optional) - If provided and set to true, the returned value will be the displayed value for the control rather than the underlying data value where appropriate (e.g. for select controls).
	RETURNS: A string containing the current value, or null if the field couldn't be found. For multiple selection controls, an array of all current values will be returned.
hyf.util.setFieldValue(fieldName, fieldValue);	Attempts to set the current value for the given field. This will attempt to determine the type of the given field name, by checking dojo widgets, any form elements, and display only containers with the given id. If the field supports multiple selections, then the provided value will be added in addition to any others that already exist.
	fieldName - The name of the field, which contains the value that is required.
	fieldValue - The value to set.
	RETURNS: None
Validation
hyf.validation.validateForm();	Validates all fields on the whole page, and shows any errors found using the error display options specified for the page. For further information you can reference the following Forum entry.
	RETURNS: boolean (true or false) indicating the outcome of the validation.
hyf.validation.validateContainer(container);	Validates all fields within a container, and shows any errors found using the error display options specified for the page.
	field - A Group component (e.g. HTML div) on the page. All fields within this container will be validated.
	RETURNS: boolean (true or false) indicating the outcome of the validation.
hyf.validation.validateField(field);	Validates the specified field, and will display an error if appropriate.
	field - The Field component (e.g. text box) on the page that should be validated.
	RETURNS: boolean (true or false) indicating the outcome of the validation.
Error Handling
hyf.FMAction.getErrorDisplay().addError(error);	Tells the page about a new custom error that should be displayed the next time validation is performed. For further information you can reference the following Forum entry.
	error - A ValidationError object describing the error. You create a ValidationError object using the field in error, and the relevant error code, e.g. new hyf.validation.ValidationError(errorField, errorCode);
hyf.validation.DisplayMessages.addMessageProducer(func, errorCode);	Tells the built in validation process about a new function that can be used to return custom error messages for display. For further information you can reference the following Forum entry.
	func - The function name reference to call. When called, this function will be passed two parameters, the Field (e.g. a text box) in error, and the code indicating the type of error.
	errorCode - (Optional) - The particular error code that this function returns messages for. If omitted, the function will be called for all errors.
Date Processing
hyf.calendar.setDateConstraint(fieldName, restrictionType, restrictionValue, repeatId);	Sets data constraints on a date field to restrict the values that can be entered. For further information you can reference the following Forum entry.
	fieldName - The name of the date field to restrict.
	restrictionType (Optional) - Set to Minimum or Maximum
	restrictionValue - Sets the restriction value applied. This can be one of the supported keywords (Today, Yesterday, Tomorrow, LastWeek, NextWeek, LastMonth, NextMonth, LastYear, NextYear), or the name of another date field whose value should be used, or a date value string. If a date value is provided, this should be in the data date format for the field.
	repeatId (Optional) - If the fieldName is in a repeating table, then the repeat Id of the specific field to constrain should be provided. This will consist of the repeat name and the row identifier e.g. orderTable4. The repeat name can be found by clicking on the repeat container when in Design Mode on the Page Design screen. Note: To constrain all the field entries in a repeat, use the hyf.calendar.setRepeatDateConstraint function.
hyf.calendar.setRepeatDateConstraint(repeatName, fieldName, restrictionType, restrictionValue, restrictionValueFieldInRepeat);	This supports setting of the appropriate constraint for a date field within a repeat structure (e.g. table). This ensures the constraint is applied to the date field for each repeat entry (row).
	repeatName - The name of the repeat the date field is contained within. This name can be found by clicking on the repeat container when in Design Mode on the Page Design screen.
	fieldName - The name of the date field to restrict.
	restrictionType (Optional) - Set to Minimum or Maximum
	restrictionValue - Sets the restriction value applied. This can be one of the supported keywords (Today, Yesterday, Tomorrow, LastWeek, NextWeek, LastMonth, NextMonth, LastYear, NextYear), or the name of another date field whose value should be used, or a date value string. If a date value is provided, this should be in the data date format for the field.
	restrictionValue FieldInRepeat - (Optional) - If set to true, then the restrictionValue is assumed to be the name of a date field within the same repeat as the field being restricted, and the appropriate repeat ID is automatically added to ensure each field being restricted is based on the field in the same repeat row.
Display Control
hyf.util.hideComponent(component, animate);	Hides the specified component to ensure it is no longer visible on screen.
	component - The Group component (e.g. a HTML div) to hide.
	animate (Optional) - Boolean (true or false) indicating whether the hiding of the component should be animated or not. Defaults to false, if omitted.
hyf.util.showComponent(component, animate);	Ensures the specified component is visible on the screen.
	component - The Group component (e.g. a HTML div) to show.
	animate (Optional) - Boolean (true or false) indicating whether the showing of the component should be animated or not. Defaults to false, if omitted.
hyf.util.toggleComponent(component, method, animate);	Toggles the display of the specified component.
	component - The Group component (e.g. a HTML div) to show/hide.
	method (Optional) - String specifying the required visibility of the component (show or hide). If omitted, or set to null, the current state will be toggled. If the value is specified, it will switch to that state if it is not already in that state.
	animate (Optional) - Boolean (true or false) indicating whether the showing of the component should be animated or not. Defaults to false, if omitted.
hyf.util.getMouseCoords(evt);	Returns the coordinates of the mouse for the supplied event.
	evt - The event object, for which the mouse coordinates are required. In custom JavaScript event actions, this is available as objEventSource.event.
	RETURNS: An object containing two properties (x and y) indicating the mouse location.
hyf.util.getComponentPosition(component, screen);	Returns the current location coordinates of the specified component.
	component - The Group component (e.g. an HTML div), for which the position is required.
	screen (Optional) - Boolean (true or false) value. If set to true, the returned values are in screen coords, i.e. they are adjusted for scrollable regions, to allow comparison with the mouse coordinates returned from the getMouseCoords method.
	RETURNS: An object containing 4 properties: x, y, width and height. The x and y values indicate the position of the top left corner of the component.
Form and Ajax Submission
hyf.FMAction.handleFormSubmission(actionParam, validateParam, objEventSource)	Performs a full page submission of the form. Example: hyf.FMAction. handleFormSubmission( {name: 'Action', option: 'Static', value: 'my_action'}, {name: 'Validate', option: 'Static', value: 'true'}, objEventSource)
	actionParam - Specifies the action to call. Supported option types: 'Static'
	validateParam - Indicates whether to validate first. Supported option types: 'Static'
	RETURNS: Boolean (true or false), indicating whether the form was submitted.
hyf.FMAction.handleAjaxSubmission(actionParam, sourceParam, targetParam, validateParam, objEventSource)	Performs an Ajax Partial Page submission of some data. Example: hyf.FMAction. handleAJAXSubmission( {name: 'Action', option: 'Static', value: 'my_action'}, {name: 'Source', option: 'AllFormData', value: ''}, {name: 'Target', option: 'PageGroup', value: 'my_group_name'}, {name: 'Validate', option: 'Static', value: 'true'}, objEventSource)
	actionParam - Specifies the action to call. Supported option types: 'Static'
	sourceParam - Indicates whether to send all the data on the page or just the data within a particular group. Supported option types: 'AllFormData', 'PageGroup'
	targetParam - Identifies the group, where the results should be placed. Supported option types: 'PageGroup'
	validateParam - Indicates whether to validate first. Supported option types: 'Static'
	RETURNS: Boolean (true or false), indicating whether the partial page was submitted. Note: Partial Page submissions are fired independently. As a result, it is not possible to confirm completion. In some situations you may need to check that it has completed successfully. Please refer to the Customising the Generated Ajax Calls Forum entry.

10 Design using Data Sources

The Data Sources tab is located on the left hand panel. When the Data Source tab is selected, you can choose from W3C Schema, Service Definition (WSDL) and SQL Database. You may also have customised additional options depending on your particular WebMaker installation. For example, you may see additional application environments listed that can be used to obtain data for creating pages. Selecting a W3C Schema or Service Definition will enable you to choose a file using the Repository Viewer. When you select the SQL Database option you can create a new database connection or select an existing connection to navigate SQL database table information. In all cases, when you have navigated and selected an appropriate item, a tree representation of the information will be displayed. You can drag and drop elements or groups of elements from this tree to create your Page Design.

Merging to accelerate development

As well as merging different controls from the palette you can also drag and drop data source fields from the Data Source tab over fields on your canvas. This can be useful during iterative development. For example, you may have painted a static select box on your page with a list of countries, but want to obtain this list from a database. You can simply select a suitable table in your database, which holds the list of countries and drag the table over your static select box and WebMaker will make the necessary changes to ensure the select box is dynamic and bound to the database table. When you drag and drop fields on to the canvas from a data source, WebMaker will pop up a wizard, to guide you and request additional information about mappings between data sources and page actions and target controllers (requires server controllers). WebMaker will assist by linking the data sources to server controllers via page actions and generate appropriate bindings and rules where possible. You can change all this, post generation to suit your exact requirements. As you complete such operations, WebMaker will start to create a list of data sources that have been used during the page creation process within the Data Sources tab. You can manage the details of the data source information and the mapping information you selected by selecting the appropriate data source item as required.

When dragging fields from a data source, you also have access to the following merge functions, when the merge mode is on:

Merge Individual Control - If you drag an individual field from a data source, you have the option to merge this with an existing field on the page. This merge will update the name of the field to match the data source element, and will also adjust the data constraints and data bindings for the field so that its value will link to the data source. This will not affect the type of control, or any of its visual characteristics. Merge Repeating Content - You can drag a repeating element from a data source (identified by an R: prefix on the tree) onto an existing repeat control representing a table structure to merge this information. This will update the name of this repeat, and its contained group, and add all the fields within the repeat in the data source alongside the table contents on your page. The bindings will also be updated to match the data source. This can be useful if you have first added a Paging Table or Editable Table from the palette, and then wish to merge that with a data source. Finally, delete the initial example columns added for the Table. Merge Repeat to a multiple select type field - You can also merge a repeat element (identified by an R: prefix on the tree) from a data source onto an individual control that provides a set of options to select from (e.g. select, radio, multiple checkbox). In this case, the target field will be updated to display a dynamic set of options as retrieved from the data source. You will be asked to select which particular entry from the data source should be used as the display value shown to the user on the page, and which provides the data id value to use in the XML messages that flow to server controllers for processing if applicable.