Pageflow and Form Guide

CHAPTER 6

Form Designer

This chapter introduces the Novell exteNd Director Form Designer and describes how to use it to create and modify XForms 1.0-compliant Web forms. It includes these sections:

• About XForms

• About the Form Designer

• Starting and stopping the Form Designer

• Creating forms

• Defining the presentation

• Working with model elements

• Working with events and actions

• Testing forms

About XForms

XForms provide a robust, standards-based way to define Web forms. The advantages of the XForms standard include:

• Separate data, logic, and presentation modules

• A powerful event model (so that you don't have to use a lot of scripting for client-side validation or calculations)

• A way to process XML data

XForms cannot run as standalone applications. They are designed to run as components within a host language like XHTML. In Novell's implementation, they run within the context of a pageflow application.

About the Form Designer

The Form Designer provides a graphical environment for developing XForms 1.0-compliant Web forms.

The Form Designer is divided into these tabs:

Starting and stopping the Form Designer

To start the Form Designer, you:

• Open an existing form (see To open an existing form: next)

  OR

• Create a new form (see Creating forms)

To open an existing form:

1. Select File>Open.

2. Navigate to the location of the existing form (usually in the project's \data\form directory).

3. Click the form file and choose Open. (Optionally, you can double-click the form.)

Creating forms

You use the Form Wizard to create either an initial unbound form or a data-bound form based on:

• Schema

• Sample XML data (instance data)

Other strategies   To create a complete pageflow including input and output forms from any other source, you'll launch a different wizard. For more information on launching other wizards that generate XForms within the scope of a pageflow application, see Database Pageflow Wizard, Web Service Pageflow Wizard, and Composer Pageflow Wizard.

To create a form using the Form Wizard:

1. Open an exteNd Director project.

   TIP:   You can't start the Form Wizard unless you have a project that contains a resource set open.

2. Select File>New.

3. On the Portlet tab, choose Form and click OK. (Alternatively, you can double-click Form.)

   The first panel of the Form Wizard displays:

   

4. Specify the following options:

   Option	What to do
   Form name	Specify a name for the form. You don't need to specify any extension.
   Use CSS layout	Check this box when you want the wizard to use absolute positioning to layout the controls on the form, otherwise, uncheck this box. If you choose not to use CSS layout, absolute positioning is not available.     For more information about how the wizard uses CSS layout, see About the wizard-generated forms.
   Standard portlet CSS classes	Check this box when you want the wizard to use the WSRP CSS classes for fonts and colors. (The defaults are defined in the wsrp-classifications.xml file located in the Common\Resources\CSSClassifications directory). When checked, these classes are used in combination with the portal theme files at runtime for styling the page. Uncheck this box if you want to define your own colors and fonts.

5. Click Next to proceed.

   The following wizard panel displays:

   .

6. Specify one of the following file types for your initial instance data:

   Option	What to do
   Schema	Choose this option if you want the wizard to generate controls that are bound to the instance data nodes created from the elements of an existing schema. The schema type of each instance data node is automatically specified.
   Sample XML data	Choose this option if you want the wizard to generate controls that are bound to instance data nodes. If you want to specify formatting for the displayed data values, you will have to add schema type information manually.
   No initial instance data	Choose this option to create XForms with no data-bound controls.
   Specify a file	Specify the name and location of the file containing the schema or the sample XML data: Browse—Choose this option when the file is located on disk. Resource Set—Choose this option when the file is located in a resource set within the currently open project.

   If you chose Schema, you are prompted to specify the root of the instance data defined by this schema on the next pane:

   1. Choose the root from the list supplied in the dropdown list.

   2. Click Next.

7. Click Next.

   The following wizard panel displays:

   

8. Specify the following options:

   Option	What to do
   Specify the number of columns for this page	Specify how many columns of controls the wizard should generate.
   Specify how to align the labels relative to the controls	Specify how the labels and the controls should be aligned.
   Specify the width for each column	Specify the width and unit for each column. The wizard converts the units to pixels.
   Specify the font size that will be used in the browser	Specify the font size and units to be used.
   Specify the gap between rows	Specify the amount of space (in pixels) between rows.
   Specify the vertical gap between the label and its control	Specify the amount of space (in pixels) between the label and control.

9. Click Finish.

10. When the wizard reports that it has finished creating the form, click OK.

What happens   When you click Finish, the Form Wizard generates an XHTML file including all of the markup necessary to:

• Build the form's model and instance elements

• Generate and bind default controls for each node of instance data

• Generate a single absolute positioning region containing default controls (and labels) for each component of the instance data

  • If the instance data contains repetitive, homogeneous child elements (indicating repeated data), the wizard generates a repeat block containing default controls

• Lay out the controls based on user input (such as the number of columns and how the label should appear)

About the wizard-generated forms

The generated forms are XForms 1.0-compliant. They reside in an XHTML file. Each form generated by the wizard has the following:

• XML namespace declarations

• XForms model element

• XForms:action elements

• <style> element

XML namespace declarations

XML namespace declarations are located at the top of the file and have this format:

  xmlns:xforms="http://www.w3.org/2002/xforms"

XML namespaces identify the XML language an element belongs to—and how to process them. Some example prefixes include:

What you do   You are not required to change the wizard-added namespaces. You may have to add new namespace declarations depending on your application.

XForms model element

The XForms model element is located within the <head> of the XHTML document. The model element defines the:

• Structure of the data displayed to or entered by the user

• Structure of the data to submit

• Data for initializing form controls

• Rules for validating user data

In the wizard-generated model element you'll see an id attribute with a name that includes _wsrp_rewrite_—like this:

  <xforms:model
     id="model1_wsrp_rewrite_">

A model ID is not required (unless there are multiple models); however, the Form Wizard always generates a model ID. The wizard-generated model ID always includes the wsrp_rewrite token. At runtime the wsrp_rewrite token is replaced with a unique name. This allows the runtime environment to manage multiple forms and models running within a single page.

What you do   You'll use the Model tab to define instance data, submission elements, and model item properties. The runtime environment will manage the replacement of the wsrp_rewrite token.

XForms:action elements

Within the model element, you'll see two predefined XForms <action> elements containing two XForms event handlers. They are default handlers for submit and data validation errors.

They provide user feedback when an error occurs on submission. They are intended to ensure that there are no silent failures for your form. They look like this:

  <xforms:action ev:event="xforms-invalid" ev:observer="div_wsrp_rewrite_">
  <xforms:message level="modal">The data is invalid. Please check it    and try again.</xforms:message>
  </xforms:action>
  
  <xforms:action ev:event="xforms-submit-error">
  <xforms:message level="modal">Submission error. Please check the
     data and try again.</xforms:message>
  </xforms:action>

What you do   No action is required, but you can modify them or remove them if you do not want your form to include this functionality.

<style> element

The <style> element contains the CSS definitions for the form and controls.

If you choose to use CSS layout (when generating the form), the styling information for the generated page is contained in CSS styling rules located in a <style> element within the <head> of the XHTML file. You can also store the CSS style rules in an external file referenced from the XHTML file through a link.

NOTE:   If you specified not to use CSS styling (when generating the form via the wizard), the generated form will not contain a style node.

The following applies to all XForms controls on a form:

  .nvP4_wsrp_rewrite_ {
  	 position : absolute;
  	 left : 10px;
  	 top : 91px;
  	 width : 67px;
  	 height : 25px;

What you do   You can modify the default CSS styling rules by:

• Creating your own style sheets and attaching them to the form

• Adding to or modifying the class styles already defined

    For more information, see Using the CSS Style Manager.

Saving forms

To save a form:

• Click the Save icon from the toolbar.

  OR

• Choose File>Save.

Defining the presentation

The Form tab provides the tools to define the user interface. This section describes how to use the Form tab. It includes these topics:

• About the Form tab

• About form controls

• Shortcut keys

• About form controls

• Manipulating controls

• Applying styles to controls

• Working with layout regions

• Working with model elements

About the Form tab

The Form tab provides a graphical way to create and manipulate the form controls that make up the user interface. The Form tab looks like this:

The Form tab provides:

Form tab limitations

Only the form controls in layout regions on the page are editable. You cannot use the Visual Editor to edit the XHTML on the page. The XHTML tags are not expanded to display their content—only the tags are displayed. You cannot insert a form control into an XHTML tag.

Shortcut keys

You can use the following shortcut keys in the Visual Editor:

About form controls

The Form Designer supports all of the XForms controls outlined in the XForms 1.0 specification and several other controls used by the Form Designer to control formatting. The controls include:

  <lastname xsi:type="xsd:base64Binary"/>

    For more information on the properties that you can specify for the controls, see Setting form control properties.

Manipulating controls

After you generate an initial form using the Form Wizard, you can refine it by adding or moving controls. You can use the Form tab for:

• Adding and removing controls

• Moving controls

• Sizing controls

• Aligning controls

• Grouping and ungrouping controls

• Binding controls to data

Adding and removing controls

Adding controls

To add unbound controls from XForms toolbar:

1. Click on the control type in the toolbar.

2. Click within the layout area to place the upper-left corner of the control on the form.

To add unbound controls from the Form Designer menu:

1. Select Form Designer>Insert.

2. Select the control from the popup menu.

3. Click within the layout area to place the upper-left corner of the control on the form.

Removing controls

You cannot remove a control without also removing its label.

To remove a control:

1. Click the control.

2. Press the Delete key.

   OR

3. Select Edit>Cut.

Moving controls

To move a control:

1. Click the control.

2. Drag it (or use the arrow keys to move it) to the new location.

To move more than one control:

1. Select the controls to move by:

   • Click one control, then press the Ctrl key and click any other control(s).

     OR

   • Click and drag a box around the controls you wish to select—any controls within the box are selected.

2. Drag the set of controls to the new location.

Sizing controls

By default, a control's width and height are unspecified so that they can automatically adjust to their content. You can specify an exact width and height in the two ways described below

NOTE:   When you define the width and height, the contents of the control wrap to to accommodate the specified size. The runtime results are not guaranteed.

To size a form control graphically:

1. Click the control so that the handles are visible.

2. Size the control by:

   • Selecting a handle and dragging it to the desired sized.

     OR

   • Selecting a handle and using the arrow keys (Shift-arrow key).

To size a form control using the Property Inspector:

1. Select the control.

2. Open the Property Inspector and specify the width and height for the control.

Aligning controls

You can align controls within a layout, repeat, or switch block.

To align controls:

1. Select the control to use as a reference, plus the additional controls that you want to align with it.

2. Choose the alignment you want (from the Align toolbar) to apply to the selected objects.

   OR

3. Choose Form Designer>Align Distribute selected objects.

Grouping and ungrouping controls

You may want to create groups of controls, because a group can:

• Provide a hint to the client side XForms renderer, so that related controls can appear together on limited capability devices, such as cell phones and PDAs.

• Simplify the XPath expressions within a group by establishing a context for the controls in the group.

• Provide a container for the controls to which you can apply CSS styles within the group via inheritance.

Rules for grouping controls

• A control can belong to more than one group.

• Groups must be strictly nested—that is, the entirety of a group must be contained by a higher-level container such as group, repeat, or switch/case blocks.

• The entirety of a control (not just the label, for example) belongs to a group.

• Be careful when using groups. Grouping a set of controls in the Form Designer does not lock the controls together spatially. You cannot ungroup and regroup a set of controls without losing information (such as the instance data context, or style information attached to the group element).

Most of these rules are required because of the hierarchical nature of XML.

To create a group:

1. Select the controls you want to group.

2. Select Add to Group from the Form Designer menu or by right-clicking and selecting it from the popup menu.

3. Choose New Group.

4. Enter a name for the group.

   The Form Designer creates the new group, and it becomes the current selection. The Property Inspector displays properties for the selected group. When the group is selected, it can be dragged around the page to reposition the controls within the group.

What happens when you group controls

When you create a group:

• The XML is reorganized to create a new group element whose parent is the parent of the control that is the primary selection.

• The selected controls become children of the new group element.

• The nodeset binding for the group node is set to the instance data node that is the "lowest" ancestor to the instance data nodes bound to the selected controls

• The XPath bindings for the controls in the new group are adjusted to become relative to that node.

• Binding specifications using the bind attribute are not adjusted.

To add a control to a group:

1. Select the control to add.

2. Select Form Designer>Group>Add to Group (or right-click to display a popup menu).

3. Select the name of the group to add the control to.

   The selection does not change to the entire group, in case there are additional commands to be performed on the selected control. The XML element for the control is moved under the group element representing the group, and the instance data binding XPath is adjusted to be relative to the node bound to the group element.

To remove controls from a group:

1. Select the control(s) to remove.

2. Right-click and select Remove from group (or select it from the Form Designer menu).

3. Choose the group from which the element should be removed.

   The XML element(s) representing the control(s) are detached from the group element and made siblings of it; the instance data XPath expressions are adjusted to absolute expressions. If no controls remain in the group, the group element is removed from the document.

To remove a group:

• To remove a group (but not its associated controls) from a form, you can:

  • Select Form Designer>Group>Remove Group.

What happens when you remove a group

When you remove a group:

• The XML elements representing the controls in the group are detached from the group element and made siblings of it.

• The group node is deleted.

• The instance data XPath expressions for the controls are adjusted to absolute expressions.

Applying styles to controls

The Form Designer provides default styles (based on standard portlet CSS class definitions) to implement color, sizing, and fonts used in the form's presentation. The default class attributes for the styles are defined in wsrp-classification.xml (located in the \Common\Resources\CSSClassifications directory). At runtime, the various portal theme files define the styles associated with these class attributes, and with some internal Novell class attributes.

Changing CSS Classifications

The wizard generates class attributes for each of the controls on a form. For example, an input field on a form could be given a name like:

  class="nvP1_wsrp_rewrite_ portlet-form-input-field"

• The nvp1 class value references a unique selector in the internal style node that specifies the absolute positioning rules for this element.

• The wsrp_rewrite is a token that is replaced at runtime to ensure unique names for all of the controls on a page in a multiportlet page.

• The portlet-form-input-field is the class name that references a formatting rule in an external style sheet (normally a portal theme file).

These classes are defined in WSRP-classification.xml in the Common\Resources\CSSClassifications directory. This file maps the class names to particular control types. These class names are added by the wizard if you check the Standard Portlet CSS Classes check box (on the first page of the wizard).

To apply CSS Classifications to a file that was not generated with these values:

1. Open the form in the Form tab.

2. Choose Form Designer>Set CSS Classification.

   The Apply CSS classifications dialog displays:

   

3. Complete the panel as follows:

   Field	Description
   Select the set(s) of classifications to be applied to this document	You must select WSRP. NOTE:   Further sets of classifications may be made available in the future.
   Apply new class values to existing controls	Check this box to have the new class values added to existing controls, as well as to new controls that get created later.
   Remove old class values from existing controls	Check this box to strip all of the classification-defined class values from the controls on the form. For example, a control with the attributes: class="nvP1_wsrp_rewrite_ portlet-form-input-field" will become: class="nvP1_wsrp_rewrite_ " If you check this box, you will lose any formatting associated with the class values that were removed.

4. Click OK.

Using the CSS Style Manager

You can use the CSS Style Manager to edit any internal or external CSS style sheets associated with your form from within the Form Designer. You can use it to specify CSS properties like background color, text color, and font size associated with specific controls and labels. (The Form Designer directly handles control and label positioning; you cannot use the CSS Style Manager for this function.)

To open the CSS Style Manager:

1. With a form open, choose Form Designer>Style Manager.

   

NOTE:   Pressing cancel on this main dialog does not cancel completed actions.

You'll use the CSS Editor to create, edit, and delete style rules for both internal and external style sheets.

    For more information, see the chapter on the CSS Editor in Utility Tools.

Working with layout regions

To allow you more precise control of the layout of the controls on a form, the Form Designer requires you to place form controls within a layout region. A layout region is a container for the XForms controls within an XHTML page. Like other form controls, you can add, remove, size, and set properties on layout regions. The following controls can act as layout regions:

• Absolute positioning region

• XForms repeat control

• XForms switch/case control

• Pageflow link region

Layout regions are identified with a gutter in the far left of the Visual Editor. :

Click the gutter to select the control for setting layout region properties, resizing, or deleting.

To add a layout region to a form:

1. Choose the layout control to add from the XForms toolbar.

2. Position the cursor to the location where you want to add the control.

   The cursor displays as a pink arrow.

   

3. Click to place the layout region.

   The layout region is added to the form.

To remove a layout region:

1. Select the layout region (it is selected when the gutter label is highlighted).

2. Right-click and choose Delete.

To resize a layout region:

1. Select the layout region to resize.

2. Grab the handles of the layout region and drag the box to the required size.

To create nested repeat blocks:

• Click the Insert XForms Repeat icon in the XForms toolbar.

  Click in the white space of an existing repeat block in the Visual Editor (click away from the block's boundary—clicking on or near the lower boundary of the repeat block adds the new repeat after, not within, the existing block).

  The Form Designer adds an empty repeat group to the form. It looks like this:

  

To create a switch block:

1. Click the Insert XForms Switch icon in the XForms toolbar.

2. Move the pointer to the white space at the bottom of the bottommost block.

   The Add New Cases to Switch dialog displays.

3. Enter two or more case IDs separated by spaces.

   You'll use the case IDs to program the behavior in the Event Editor.

4. Click OK.

   The The Form Designer adds a switch block with a case block for each case id you entered.

5. Add controls to the case layout regions, as described in Adding and removing controls.

TIP:   You can add or remove cases by selecting the switch box, right-clicking and choosing the action from the popup menu.

Setting form control properties

Properties are attributes that you can set at design time for a particular control. You specify property values in the Property Inspector. See the table below for properties specific to the exteNd Director extensions (such as the Pageflow link region) or conveniences (such as the Alert literal text). For all other definitions, see the XForms specification.

Binding controls to data

The Form Designer makes it easy to bind controls to a single node or a node set. In many cases you won't need to take any action to bind a control to data. For example:

• The Form Wizard automatically creates data-bound controls

• When you drag a data node from the Instance Data Pane onto a control in the Visual Editor, the Form Designer generates the data bindings automatically

If you want to modify the generated bindings, or if you want to bind controls that you've added to the form from the toolbar, you can use the Property Inspector to specify the binding attributes. You can also set up a <bind> in the Model tab, then set the bind property to the <bind> element's ID. See Binding elements to controls.

NOTE:   The following procedure generates a binding via a <ref> attribute on the control. It's possible to specify either a <ref> or a <bind>. When you specify one, the Form Designer removes the other. If you enter both via the Source tab, the <bind> takes precedence.

To bind a control to a single node via an XPath:

1. In the Visual Editor, select the control you want to bind.

2. Using the Property Inspector, specify the model ID (when there is more than one model element for the form).

3. Specify the XPath by:

   • Typing the XPath in the text box of Reference (generates a <ref> attribute)

     OR

   • Launching the XPath Navigator (by clicking the ellipsis next to the XPath text box)

     1. In the XPath Navigator dialog, locate the node you want to bind to and select it.

            For more information on using the XPath Navigator, see the chapter on scoped paths and XPaths in Developing exteNd Director Applications.

     2. Click OK to return to the Form Designer.

To bind a control to a node set:

NOTE:   <repeat> elements require that you bind to a node set.

1. In the Visual Editor, select the control you want to bind.

2. Using the Property Inspector, specify the model ID.

   1. In the XPath Navigator dialog, locate the node you want to bind to and select it.

          For more information on using the XPath Navigator, see the chapter on scoped paths and XPaths in Developing exteNd Director Applications.

   2. Click OK to return to the Form Designer.

   NOTE:   If a <ref> resolves to multiple nodes, the first node is used.

Populating the Select controls

There are two ways to provide a list of values for the Select controls:

List values   Lists have two types of values:

• A label (for display)

• A value (for storage)

The user sees the label, but the associated value is the value written to the instance node. This allows you to display user-recognizable text while storing keys or other types of codes in the instance node. For example, if you entered the words apples, oranges, and pears, these words would appear in the display list. However, selecting apples might return the value 1, oranges could return 2, and so on.

Instance elements   A Select control is usually associated with two instance elements:

• One containing the display values

• One containing the element to which the value is written

To load the list statically:

1. Highlight the Select control and access the property sheet.

2. Choose the Edit Select Choices link.

   The Select Control Choices dialog displays.

   

3. Click the Static Choices radio button.

4. The dialog enables the Label and Value text boxes:

   • To change the predefined Label and Value choices, double-click within the text box and change the text.

   • To add a new choice, click Add, and place the cursor within the added text box and add the Label and Values.

5. When you are done, click OK.

To load the list dynamically:

1. Highlight the Select control and access its property sheet.

2. Choose the Edit Select Choices link.

   The Select Control Choices dialog displays:

   

3. Click the Dynamic choices radio button.

4. Choose the model from the dropdown list box.

5. Click the ellipsis next to the Nodeset XPath to access the XPath Navigator to choose a nodeset.

6. Click the ellipsis beside Label XPath to access the XPath Navigator to the display value.

7. Click the ellipsis beside the Value XPath to access the XPath Navigator to choose storage value. This value is written to the instance node.

8. When you are done, click OK.

Working with model elements

The XForms model element defines the structure of the XML data available to the form. It defines the:

• Structure of the data displayed to or entered by the user

• Structure of the data to submit

• Data for initializing form controls (instance data)

• Rules for validating user data

The Model tab includes these elements:

About the Model tab

The Model tab provides a graphical way to define the elements that comprise the form's model. The Model tab looks like this:

The Model tab provides:

Specifying model elements

By default, the wizard-generated forms include a model.

To add a model element:

1. With the form open in the Model tab, click Add (at the top of the Model Editor).

   The following dialog is displayed.

   

   You'll see that wsrp_rewrite_ is appended to the model ID name. This is a placeholder that is recommended. At runtime the wsrp_rewrite_ is replaced with a unique ID to ensure that no naming conflicts occur among other forms or portlets on the same page.

2. Name the model and click OK.

   The Form Designer creates a new, empty model tree and displays it in the Model Editor.

To remove a model element:

1. With the form open in the Model tab, select the model element you want to delete from the dropdown list box.

   

2. Click Delete.

Specifying model properties:

1. Select the model in the Model Editor.

2. Access the Property Inspector and complete the properties as follows:

   Property	Description
   ID	Specifies a unique identifier for a model. A model ID is not required (unless there are multiple models), but the Form Wizard always generates a model ID and uses the token wsrp_rewrite. It is good practice to use an ID because at runtime there might be multiple portlets with multiple XForms on a single page.
   Schema URI	Specifies a list of external schema documents that are needed to describe the structure of the instance data and allow it to be validated. To add schema documents: Click Edit schema list. (The Edit Schema File List dialog displays). Click Add. In the Select Schema File dialog, specify the name and location of the schema file. Click OK. Click OK.

    For information about adding events, see Customizing event handlers.

NOTE:   Some element types only allow you to add elements to the root (like Instance). Others allow you to nest elements within other elements (like bind). You can determine which elements can be nested by selecting an element (not the root) and right-clicking to see if Add item is offered on the menu.

Specifying instance elements

To set instance data properties:

1. Select an instance element (not the root).

   The instance element's properties are displayed in the Property Inspector. They include:

   Property	Description
   ID	A unique identifier for the instance data. This is necessary only when there are multiple instance data nodes in a single document. It is good practice to always allow the Form Designer to add _wsrp_rewrite_ because at runtime there might be multiple portlets with multiple XForms on a single page.
   Use pageflow data at runtime?	Specifies how instance data should be handled at runtime (once the form is incorporated within a pageflow). Options are: always (the default)—Always replace the data at runtime. If no replacement data is available, a runtime error is generated. if-available—Replace only if new data is available at runtime; otherwise use the design-time data. delete-if-not-available—Use new data if it is available at runtime. Don't ever use the design-time data—delete it. never—Use the design-time data alone. IMPORTANT:   When you incorporate a form into a pageflow (as an XForms activity), you'll be able to specify a set of scoped paths (using the Property Inspector for the activity), indicating the replacement data for each of the replaceable <xforms:instance> nodes. (These are the instance nodes whose Use pageflow data at runtime is set to always, if-available, or delete-if-not-available. )
   Is primary instance data?	Specifies whether data for an <xforms:instance> node is treated as the primary instance data. The primary instance data is the input data to the page rendering's XSLT transformation; it is the default context for use in XSLT expressions in the page. All other input data is secondary input data and can be accessed only via variable references in XSLT expressions.     For more information, see About runtime replacement of instance data.
   Is inline?	Check this box when data is contained within the model element of the form. When this is checked, you can use the instance data generated by the wizard or you can import the instance data from a file located within the project's resource set. See Import instance data from file (below). Uncheck this box when you want the data to be referenced from an external file. See Source (URI) (below).
   Import instance data from file	To import instance data: Click the ellipsis button. In the Import File into Instance Node dialog, Type the name of the file to import. or Click Import, navigate to the file to import, and click Open. Click OK.
   Source (URI)	When the data is not inline, you can specify the location of the data using a URI. NOTE:   The URI must reference a location within the current project's resource set. To add a link to the instance data: Click the ellipsis next to the Source URI text box. In the Select File dialog, choose the file and click OK.

About runtime replacement of instance data

At runtime, the form's data is replaced as specified by the Use pageflow data at runtime? property. The data is replaced for each form (which runs as a portlet) separately, and it happens before aggregation into the portal page. Additionally, the data corresponding to one or more input documents may be made available, according to the following rules:

    For more information on adding events to the instance element, see Working with events and actions.

Specifying actions

The Form Designer provides multiple ways for defining actions within your form:

The remainder of this section describes how to specify actions in the Model tab.

To create an action/event handler:

1. From the Model tab, select the top-level action node from the model tree.

2. Right-click and choose Add item.

3. Navigate to the Property Inspector and supply the following properties:

   Property	What to specify
   ID	Provide a unique name for the action/event handler.
   Event name	Choose the event from the dropdown list.
   Observer	(Optional) Choose an element as the observer.
   Target	(Optional) Choose an element as the target of the action.

4. Right-click and choose the action you want performed for the event.

5. Navigate to the Property Inspector to define the specification for the selected action.

Specifying submission elements

The submission element defines:

• The structure of the data to submit

• Where to submit it

• How to submit it

To create a submission element:

1. From the Model tab, select the top-level submission node from the model tree.

2. Right-click and choose Add item.

3. Navigate to the Property Inspector and supply the following properties:

   Property	Description
   ID	Specifies a unique ID for the submission element.
   Binding ID	Specifies the ID of a Bind element. Choose the ID of the bind element that specifies the node(s) to submit.
   XPath of reference	An XPath specifying the node(s) to submit.
   Action (URI)	Specifies the URI to the location where the submission is sent.
   Method	Specifies how to do the submission. Values: Post Get Put form-data-post multipart-post (treated like a Post) urlencoded-post
   Replace	Specifies what the processor should do with the document returned after the submission. Values: all (the default) instance none
   Separator	Specifies what separator character to use on url-encoded serialization. Values: ; &
   Indent	For application/xml serialization only. Specifies whether to insert white space. Values: True False
   Standalone	For application/xml serialization only. Specifies whether to include a declaration. Values: True False
   Omit XML declaration	For application/xml serialization only. Specifies whether to include an XML declaration. Values: True False
   Encoding	For application/xml serialization only. Specifies the type of encoding to use.
   Edit namespace list	For application/xml serialization only. Specifies the namespaces to include in the serialized XML. Not specifying any namespaces is the same as specifying all. To edit the namespace list: Click edit namespace list. Select the namespaces you want to include. Use Shift to select a contiguous group and Ctrl-Shift to select multiple non-contiguous items. Click OK.
   Mediatype	Specifies the Internet media type for the serialized instance data.
   Version	For application/xml serialization only.
   CDATA section elements	For application/xml serialization only. To add CDATA elements: Click Edit CDATA element list. In the Edit CDATA item list dialog, click Add. Type the name in the Add List dialog. Click OK. Click OK.

    For more information on adding events to the submission element, see Working with events and actions.

Specifying Bind elements

Use the Bind element to set rules on the instance data. For example, you can define fields as required, enabled, or disabled depending on selections that the user makes, and so on. You can also use a bind element as an indirect way of specifying the binding for a control; instead of using <ref> or <nodeset>, use the bind=bindingID attribute on the control. Once you have defined the bind elements in the Model tab, you can return to the Form tab and associate them with form controls to create a UI Binding expression.

To create a bind element:

1. Select bind.

2. Right-click and select Add item.

To delete a bind element:

1. Select the bind element.

2. Right-click and select Delete item.

To set properties on a bind element:

1. Select the bind element.

2. Access the Property Inspector and complete the properties as follows:

   Property	Description
   ID	A unique ID for the bind element.
   XPath of Nodeset	The node(s) in the bind.
   Model Item Properties	Lets you define the model item properties to apply to the nodes defined in the XPath of Nodeset above.     For more information, see Specifying model item properties below.
   Type	Specifies the XML schema data type for the associated node. The Form Designer includes a convenience that allows you to specify formatting for certain data types. Only the data types shown in bold support this formatting. You apply the formatting in the Form tab Property Inspector for the control bound to such a node.     For more information, see Format

Specifying model item properties

You can specify these Model Item properties like this:

Informing users of validation errors

The Form Designer makes it easy to notify users that a control (or the form) has failed one of the model item property validation tests.

To notify users of an error:

1. When you've defined the model item properties, access the Form tab.

2. Select the control bound to the node for which the model item property is defined.

3. In the Property Inspector for the control, access the Hints tab.

   

4. Choose the Binding associated with the model item property definition from the dropdown.

5. Type a message in the Alert literal text to display to the user when a failure is encountered.

Binding elements to controls

When you've defined the bind elements in the Model tab, you can return to the Form tab and associate them with form controls to create a UI Binding expression.

Working with events and actions

XForms supports and extends the DOM Level 2 event model which is based on the XML event model.

You use the Event Editor to create event handlers and define XForms Actions.

This section includes the following information:

• About the Event Editor

• XForms Actions Reference

• Customizing event handlers

About the Event Editor

The Event Editor is available on both the Form tab and the Model tab. It looks like this:

The Event Editor is enabled when you select an item that allows event handlers such as a form control, a submission element, or a bind.

The Event Editor supports all XForms events and actions, but not all events are presented as choices when creating an event handler. If an event is not presented as a choice, you can type it in the choice box or use the Source tab to define it.

To launch the Event Editor:

1. Navigate to the bottom of Form Designer (in the Form or Model tabs).

2. Click the icon next to the Event Handlers label. The following graphic shows the location of the icon in the Form tab.

   

   The Event Editor opens.

3. Select a form control or model item for which you want to define an event.

   The Event Editor is now available to edit existing or create new Event Handlers.

To create an event handler:

1. Select the element that you want to define the event handler for.

   

2. Click the Create a new event handler icon.

   

   The Create Event Handler for Element dialog displays:

   

3. Choose an event from the Event Type dropdown, or type an event name (if it is not listed).

   1. If you want to further customize the event handler by adding observers, and default actions, click Advanced options and see To customize event dispatching:.

4. Click OK.

   The Event Editor now allows you to choose XForms Actions to respond to the event handler (described next).

   NOTE:   You can't put an event handler on the instance element because instance nodes are restricted to a single child element. When you use the Event Editor to add an event handler to the instance element, it will put it on the model.

To specify XForms Actions for an event handler:

1. After creating an event handler, click the New Action icon.

   

2. Select an XForms Action from the popup list.

   The selected action and it's properties are displayed.

3. Complete the properties.

4. Save the form.

The Event Editor generates the event handler and XForms Action defined by the properties you specified.

    For more information about Action properties, see the XForms specification.

To delete an action:

1. Select the action from the Action List.

2. Click the delete icon.

   

To delete an event handler:

1. Select the event handler from the Event Handler list.

2. Click the delete icon.

   

XForms Actions Reference

Click an action to display complete information.

Delete

Description

Deletes a specific node of repeated instance data. Typically, the nodeset is bound to a repeat block.

Attributes

To construct the action, use the Event Editor to define it's attributes.

Complete the attributes as follows:

Dispatch

Description

Dispatches XForms events to a named element on a form. You can dispatch events that are:

• Standard XForms events—like xforms-enabled, xforms-disabled, and so on.

• Custom XML events—A custom event that you've defined for the form.

Attributes

To construct the action, use the Event Editor to define the attributes.

Complete the attributes as follows:

Insert

Description

Inserts a new node of instance data. The XForms Specification requires that the instance data be a homogeneous collection (typically, a repeat block).

By default, the inserted node is a duplicate of the last node in the nodeset.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Load link

Description

Navigates an URL in the same or different browser window.

To test the Load link action, use View in browser option (available from the XForms Preview tab). The Load Action is not supported in Preview mode.

If the link fails at runtime, no navigation occurs and the xforms-link-error event fires. You can set up an event handler for the xforms-link-error event to intercept and handle this error gracefully.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

  http://www.novell.com

Message

Description

Launches a modal, modeless, or ephemeral message box.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

  http://www.myserver.com/error-msg/data-error.txt)

  if(string-length("account-info/account-number")>4),'You have entered too many characters.', `The data is invalid')

Rebuild, Recalculate, Refresh, and Revalidate model

Description

Forces xforms-rebuild, xforms-recalculate, xforms-refesh and and xforms-revalidate events to occur. Use the corresponding actions to specify a behavior different from the default for these events.

    For more information on XForms event processing flow, see the xforms-rebuild, xforms-recalculate, xforms-refresh, and xforms-revalidate events in the XForms 1.0 Specification.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Reset model

Description

Sets the instance data, of the specified model, to the values at form initialization.

    For more information on XForms event processing flow, see the xforms-reset event in the XForms 1.0 Specification.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Send instance data

Description

Forces the form to begin submit processing.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Set Focus

Description

Use Set Focus to move focus to a specific form control.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Set index in repeat

Description

Use the Set index to specify the current node of a repeat block.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Set value

Description

Use to set the value of an instance node.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

  This is a test value.

  concat('Test: ', /data:test/data:form_data/data:instance_node)

Toggle select case in switch

Description

Use to specify the case to display in a Switch element.

Attributes

To construct the action, use the Event Editor to define it's attributes:

Complete the attributes as follows:

Customizing event handlers

To customize event dispatching:

1. Access the Advanced Options dialog by:

   • Clicking Advanced options when you first choose the event you want to dispatch

     OR

   • Clicking Options from the Event Editor.

2. Complete the dialog as follows:

   Option	Description
   Handle event at observer element	Choose an observer element from the list box. This option moves the event handler to the selected XML element. NOTE:   You should not put an event observer on the body tag. To achieve the same result, click Attach event handler to model, select a model, and specify the body element as the observer.
   Handle event during phase	Lets you control the order in which event handlers are executed.
   Restrict handler to events on selected element	This is valid only when the event handler is attached to an ancestor of the selected control; it makes the handler specific to the selected control. You can use this option to cause something to happen at a particular point in the event-handling sequence for the specified control.
   Continue event propagation after handlers at this element	When used in combination with handlers on ancestor nodes and phase options, this is a way to control which event handlers are executed for a particular event.
   Perform or cancel default action button	Provides a means of overriding the default behavior of the XForms processor. Choosing cancel always cancels the default behavior—no conditional processing is allowed. (Not all XForms events allow you to cancel the default behavior.)

3. Click OK.

Testing forms

You'll want to test your form's data processing logic and its look and feel. The Form Designer provides built-in tools for each of these tasks:

Using XForms Preview

XForms Preview uses a Swing renderer to render the XForms controls on the page. This feature is especially useful for testing the structure of your submitted data.

To use XForms Preview:

1. Open the form.

2. Choose the XForms Preview tab.

   The form is rendered and is available for interaction:

   • Any controls that are unexpectedly disabled (you didn't mark them disabled in your code) might indicate a data binding problem.

   • You can view submission nodes in the left pane of the XForms Preview.

XForms Preview limitations   The XForms Preview does not display any HTML associated with the XHTML page.

Using View Form in browser

The View Form in browser uses an XHTML renderer to display both the XHTML and the HTML on a single page. This feature is especially useful to help you work out any layout issues.

To use View Form in browser, your form's project must be deployed to an application server. Once your project is deployed, changes that you make to the form are immediately available—you don't have to redeploy your project.

To use View Form in browser:

1. Open the project.

2. Open the form you want to view.

3. Choose XForms Preview.

4. Choose the View Form in browser button.

   The Specify Location of Processor Servlet dialog displays:

   

5. Complete the dialog using the following values:

   Field	What to specify
   Location of processor servlet	Specify the name of the server where the Form's project is deployed.
   Use default browser	Choose this radio button if you want the Form Designer to locate the default browser for the current machine.
   User browser	Choose this radio button and the corresponding text field to specify a browser other than the default.

6. Click OK.

   The form displays in the browser. If you receive a Page Not Found error, make sure that the form's project has been deployed to the server specified.

    For more information on deploying, see the chapter on deploying in Developing exteNd Director Applications.

Testing portal themes

You may want to test what your form would look like using various portal themes.

To test what your form would look like using a portal theme:

1. Open the form in the Form tab.

2. Choose Form Designer>Set Portal CSS Theme.

   The Apply Portal Themes dialog displays:

   

3. Complete the panel as follows:

   Field	What to specify
   Use portal theme?	Choose yes to apply a theme.
   Choose the portal theme for this page	Choose the portal theme to apply.

4. Click OK.

This styling applies only at design time. The Form Designer deletes the link to the theme file when the file is saved and restores it when the file is reopened (in the Form Designer). To remove the link completely, reopen the dialog and choose No.

The portal theme is not used by XForms Preview or View form in browser.

Testing browser font sizes

You may want to test your form with various font sizes.

To test browser font sizes at design time:

1. Open the form in the Form tab.

2. Choose Form Designer>Set browser font override.

   The Set override font displays:

   

3. Complete the dialog as follows:

   Field	What to specify
   Override font?	Choose yes to override the browser's font size in the design environment.
   Choose the override font size and units for this page	Specify the font size and units to be used.

4. Choose OK.

   The font you specify is applied as a font size style on the <body> tag.

This styling applies only at design time. The Form Designer deletes the link to the theme file when the file is saved and restores it when the file is reopened (in the Form Designer). To remove the link completely, reopen the dialog and choose No.

Validating the form's XML structure

You can validate the form to ensure that its XML is well formed and that it conforms to the schemas for the declared namespaces that can be resolved.

To validate a form:

1. Select Form Designer>Validate.

Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...