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:

 
Top of page

About XForms

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

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.

 
Top of page

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:

Tab

Description

Form

Lets you define the form's user interface. You can graphically:

  • Lay out and style form controls

  • Bind form controls to data

  • Define events and actions for form controls

For more information    For more information, see Defining the presentation.

Model

Lets you define the form's model elements. You can:

  • Create and edit models

  • Create and edit instance data

  • Set up data constraints

For more information    For more information, see Working with model elements.

Source

Launches a powerful XML source editor.

For more information    For more information on working using the XML Editor, see the chapter on the XML Editor in Utility Tools.

XForms Preview

Lets you run a form in test mode.

For more information    For more information, see Testing forms.

 
Top of page

Starting and stopping the Form Designer

To start the Form Designer, you:

Procedure 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.)

 
Top of page

Creating forms

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

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.

Procedure 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:

    frmWizardName

  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    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:

    .frmWizardSource

  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:

    frmWizardFormatting

  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:

 
Top of section

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

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:

xmlns prefix

Description

xforms

Treated as XForms language elements

ev

Treated as XML event language elements

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:

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:

Each control...

Details

Resides in a layout region

A layout region is a container for the XForms controls on an XHTML page. It allows you to position controls more precisely.

  • All layout regions must have the same width. The layout region is defined by a single selector on the form. The selector is:

      nv-block-width_wsrp_rewrite_ 
    

Each layout region has an individual rule to define height.

Is assigned a class attribute beginning with .nvP followed by a number

The numbers are assigned sequentially.

Each control name also contains the token _wsrp_rewrite_ . The token is replaced at runtime and is used to ensure uniqueness of control names when more than one form resides in a single page.

Is styled according to the CSS box model and the CSS pseudo element :: value

There are three types of controls—

  • Controls with no label, like <repeat>

  • Controls with an integral label, like <trigger>

  • Controls whose labels can be positioned separately from the text field, like <input>

Controls with an integral label are given one selector. For example:

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

Controls with separate labels are given three selectors. For example:

  • One for a wrapper:

      .nvP1_wsrp_rewrite_ {
      	 display : block;
      }
    
  • One for the control's label:

      .nvP1_wsrp_rewrite_ xforms|label {
      	 display : block;
      	 position : absolute;
      	 left : 10px;
      	 top : 1px;
      	 width : 73px;
      	 height : 20px;
      }
    
  • One for the data area of the control:

      .nvP1_wsrp_rewrite_::value {
      	 display : block;
      	 position : absolute;
      	 left : 88px;
      	 top : 1px;
      	 width : 88px;
      	 height : 20px;
    

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

For more information    For more information, see Using the CSS Style Manager.

 
Top of section

Saving forms

Procedure To save a form:

 
Top of page

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:

 
Top of section

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:

FormDesignerMainPanes

The Form tab provides:

Tool

Description

Visual Editor

Use the Visual Editor to graphically create and manipulate the controls. The editor includes a tabbed toolbar that includes:

  • XForms toolbar—the set of controls and blocks that you can drop on your form.

  • Align/Distribute toolbar—allows you to change the way selected controls are aligned (left/right) or distributed (vertically/horizontally).

Instance Data Pane

Use the Instance Data Pane to bind instance nodes to form controls.

You cannot use the Instance Data Pane (in the Form tab) to modify the structure of the instance data. Use the Instance Data Pane in the Model tab for those types of functions.

Property Inspector

Use the Property Inspector to manipulate the CSS and data binding properties on the currently selected control.

For more information    For more information on using the Property Inspector, see Setting form control properties.

Event Editor

Use the Event Editor to define the events and actions for controls on the form.

For more information    For more information, see Working with model elements.

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.

 
Top of section

Shortcut keys

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

Keystroke

Description

Ctrl-X

Cut

Ctrl-C

Copy

Ctrl-V

Paste

Delete

Delete

Arrow keys (left, right, up, down)

Moves the selected object 5 pixels in the corresponding direction

Ctrl-arrow key (for example, Ctrl-right arrow)

Moves the selected objects 1 pixel in the corresponding direction

Shift-arrow key (for example, Shift-right arrow)

Stretches the selected object 5 pixels in the corresponding direction

Ctrl-Shift-arrow key (for example, Ctrl-Shift-right arrow)

Stretches the selected objects 1 pixel in the corresponding direction

 
Top of section

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:

Icon

Control

Description

frmButtonControl

XForms trigger control

A standard XForms trigger control. For example, a button on a form.

Allows user-triggered actions.

XFormsTriggerStyledLink

XForms trigger styled as a link

A standard XForms trigger control preconfigured to emulate a link. CSS rules are applied to make the trigger look like a link not a button.

This means that:

  • The trigger contains an <xforms:action> event handler that listens for the DOMActivate event (button press).

  • The action element contains an <xforms:load> element that loads a new page via an HTTP GET operation. Use the control's property sheet to specify the URL to use for the GET.

For more information    See also Emulate link, Style as link, Request type, Target URL, Submission in the section on Setting form control properties.

frmOutputControl

XForms output

Displays read-only data to the user.

This control supports the format property which allows you to specify formatting for certain data types. You apply the formatting in the Property Inspector .

frmTextAreaControl

XForms text area

Allows users to enter freeform, multiline content.

frmUploadControl

XForms upload control

Allows users to upload a file from the local file system.

IMPORTANT:   The instance node to which the upload control is bound must be defined as a schema type of base64Binary or you will encounter inconsistent behavior at runtime. For example:

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

frmInputControl

XForms input

Allows users to enter single-line freeform data.

This control supports the format property which allows you to specify formatting for certain data types. You apply the formatting in the Property Inspector .

For more information    For more information, see Format.

frmRangeControl

XForms range

Allows users to select from a sequential range of values.

frmSecretControl

XForms secret

Allows users to enter single-line freeform data. The characters are disguised during data entry. Useful for things like passwords.

frmSelect1Control

XForms Select One

Allows users to select a single item from a set of choices.

frmSelectMany

XForms Select Many

Allows users to make more than one selection from a set of choices.

frmSubmitControl

XForms submit button

A special form of trigger that allows users to submit the contents of the form.

frmXHTMLImageControl

XHTML image

Displays an XHTML image loaded from the project's resource set. Visible in the Form tab, and View form in browser modes.

frmHTMLContentBoxControl

HTML content box

Read-only display of static HTML content.

frmAbsPosControl

Absolute positioning region

exteNd Director extension. Used for managing layout.

frmRepeatControl

XForms repeat

Use to display collections of homogeneous data.

To manage the repeated elements, add a repeat block to the form, then add the controls representing a single instance of the repeated data within the repeat block.

At runtime the processor renders the repeat block once for each data element that the repeat control is bound to. Each instance of the repeated data is processed as a block. Each block is placed below the preceding block. All of the remaining, nonrepetitive content is placed below that.

You cannot directly position nonrepeated objects :

  • Below the repeated elements within the repeat block

  • To the right of the repeated elements within the repeat block

frmSwitchControl

XForms switch

Use to perform conditional processing of controls on the form.

The switch element allows any number of case elements as children. Each case represents a subform, exactly one of which is rendered at any time by the runtime processor. The case rendered is determined by an action in an event handler not based on the result of a calculation.

The Form Designer represents switch elements as a layout region for each case element.

You cannot specify the order of the case statements within a switch block—but that is not necessary, since only one will be displayed at a time. The event handler determines how cases are displayed in response to the events that you specify.

frmPageflowlinkRegion

Pageflow link region

exteNd Director extension.

At runtime this control is replaced with one or more submit buttons.

For more information    For more information, see Button link.

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

 
Top of section

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

Adding controls

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

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

Procedure To remove a control:

  1. Click the control.

  2. Press the Delete key.

    OR

  3. Select Edit>Cut.

Moving controls

Procedure To move a control:

  1. Click the control.

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

Procedure To move more than one control:

  1. Select the controls to move by:

  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.

Procedure To size a form control graphically:

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

  2. Size the control by:

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

Procedure 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:

Rules for grouping controls

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

Procedure 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:

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

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

Procedure To remove a group:

What happens when you remove a group

When you remove a group:

 
Top of section

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"

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

Procedure 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:

    frmApplyCSSClassification

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

Procedure To open the CSS Style Manager:

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

    FormDesignerStyleManager

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    For more information, see the chapter on the CSS Editor in Utility Tools.

 
Top of section

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:

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

frmLayoutGutter

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

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

    PinkArrow

  3. Click to place the layout region.

    The layout region is added to the form.

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

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

Procedure To create nested repeat blocks:

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

Property name

Description

Applies to

Alert literal text

The text displayed in an alert box.

For more information    See Informing users of validation errors

All controls for which model item properties can be defined

Button height

Specifies the height of buttons added to the Pageflow link region at runtime.

The default is 25.

Pageflow link region

Button layout

Specifies the layout of the buttons added to the Pageflow link region at runtime.

The default is Horizontal.

Pageflow link region

Button spacing

Specifies the spacing between the buttons added to the Pageflow link region at runtime.

The default is 5 pixels.

Pageflow link region

Button width

Specifies the width of the buttons added to the Pageflow link region at runtime.

Pageflow link region

Dynamic choices

For more information    See Populating the Select controls

XForms Select Many

Edit class style rules

Launches a dialog that lets you:

  • Modify the CSS class styles on the currently selected control

  • Create new or edit existing styles (by launching the CSS Editor)

All controls for which CSS styling applies

Emulate link

Defines a trigger control's appearance.

Checked—Trigger is styled as a link. Adds an <xforms:action> event handler that listens for the DOMActivate event (button press). The action element contains an <xforms:load> element that loads a new page via an HTTP GET operation (and thus the Request type is set to Get).

There is no default URL to use for the GET; you have to add that via Target URL.

UnChecked—Trigger is styled as a button.

XForms trigger control, XForms trigger styled as a link, Pageflow link region

Field type

Sets the data type that the control assumes for the instance item it is bound to.

Use this in conjunction with the Format property.

Make sure that you specify a field type that is valid for the data type of the field. When there is a conflict between these two types:

  • The instance node the form control is bound to becomes invalid.

  • The event xforms-invalid is dispatched to form controls bound to that node.

  • The form control becomes invalid and thus the CSS styles with the :invalid pseudoclass apply.

  • If the invalid instance node is part of the document fragment being submitted, the submit fails.

See also Format

All controls that can be bound to data

Format

Specifies how to format the data when displaying it.

Valid formats are:

Number, currency, percent, ###,###.##, #####0.##, #####.00

See also Field type

All controls that can be bound to data

Hint literal text

The text displayed in a tooltip.

All visible controls

ID

A unique identifier for the control.

All controls

Label

The text displayed for the control's label.

All controls that can have a label

Model ID

The ID of the model associated with the Form control.

All controls that can be data bound.

Request type

Get—Uses the <xforms:load> action. Requires a Target URL property.

Post—Uses the <xforms:send> action. Requires a Submission property.

XForms trigger control, XForms trigger styled as a link, Pageflow link region

Source

Specifies the name of the source file containing the XHTML image to insert.

XHTML image

Style as link

Checked—The XForms Trigger control is styled as an HTML link.

Adds a CSS class selector (nv-link-style) to the trigger's class attribute. This CSS selector styles the trigger to look like the default appearance of the HTML <a> tag. This selector rule is added to the page's <style> node so you can modify it to look the way you want.

All triggers marked to emulate links share this same style.

Unchecked—Removes the selector name from the trigger's class attribute, but does not delete the selector rule from the <style> node.

XForms trigger control, XForms trigger styled as a link, Pageflow link region

Submission

Specifies the value of <xforms:send>'s submission attribute. (This is the ID of an <xforms:submission> in the <xforms:model>.)

XForms trigger control, XForms trigger styled as a link, Pageflow link region

Target URL

Specifies the value of <xforms:load>'s resource attribute.

(The URL that a GET is sent to in order to load the new page.)

This URL automatically gets marked up for URL rewriting in the portlet context, so specifying a relative URL here will get back to your portlet.)

XForms trigger control, XForms trigger styled as a link, Pageflow link region

 
Top of section

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:

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.

Procedure 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:

Procedure 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    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:

Method

Enables you to

When to use

Statically

Specify the list values while you are designing your form.

Use this method when the list is relatively short, you know what the values are, and the values won't change.

Dynamically

Specify the list values come from a nodeset.

Use this method when the information is located in an XML file.

When you do not know what the list items will be or the list changes frequently.

List values   Lists have two types of values:

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:

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

    pfSelectStaticChoices

  3. Click the Static Choices radio button.

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

  5. When you are done, click OK.

Procedure 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:

    pfSelectDynamicChoices

  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.

 
Top of page

Working with model elements

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

The Model tab includes these elements:

Element

Description

For more information, see

Model

The model root

Specifying model elements

instance

Points to or contains the data used to initialize the form

Specifying instance elements

action

Defines event handlers and actions that can be accessed from any part of the form

Specifying actions

submission

Defines the set of data to submit and how to submit it

Specifying submission elements

bind

Defines properties (called model item properties) of the instance data—like readonly, relevant, calculations, and indirect binding, and so on

Specifying Bind elements

 
Top of section

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:

frmModelPane

The Model tab provides:

Tool

Description

Model Editor

Use to add and remove elements.

Instance Data Pane

Use the Instance Data Pane to modify the structure of the instance data.

For more information    For more information on using this tool, see XML Editor in the online Utility Tools.

Property Inspector

Use to create and modify attributes on the selected model element.

Event Editor

Use to define the events and actions on the selected model element.

 
Top of section

Specifying model elements

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

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

    frmModelNew

    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.

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

    frmModelSelect

  2. Click Delete.

Procedure 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:

    1. Click Edit schema list. (The Edit Schema File List dialog displays).

    2. Click Add.

      1. In the Select Schema File dialog, specify the name and location of the schema file.

      2. Click OK.

    3. Click OK.

For more information    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.

 
Top of section

Specifying instance elements

Procedure 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    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:

    1. Click the ellipsis button.

    2. In the Import File into Instance Node dialog,

      1. Type the name of the file to import.

      or

    3. Click Import, navigate to the file to import, and click Open.

    4. 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:

    1. Click the ellipsis next to the Source URI text box.

    2. 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:

Rule

Description

No replaceable <xforms:instance> element is specified as the primary instance data.

  • If there is only one instance element, that one instance element is treated as the primary instance data. The primary input document is mapped to the primary instance data.

  • If there is more than one default <xforms:instance> element in the page, one instance element must be defined as the primary instance data—and:

    • All other replaceable <xforms:instance> elements use secondary input data.

    • All secondary input data is made available to XSLT expressions in the page via XSLT variables. XSLT allows only a single input document, so other documents must be made accessible via the XSLT variable mechanism.

    • The variable identifiers are equal to the ID of the corresponding <xforms:instance> elements. (You use a dollar sign in XSLT to access a variable in an XPath expression; thus if you had <xforms:instance id="foo"> you'd access its runtime data via something like <xsl:value-of select="$foo/a/b/c"/>.)

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

 
Top of section

Specifying actions

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

Method

Description

The action node of the Model tab

Use the action node of the Model tab as a place to create one or more actions (with unique IDs) and then reference them elsewhere in your form.

The Event Editor in the Form tab

Use the Event Editor launched from the Form tab to create actions for your form controls

For more information    For more information, see Working with events and actions.

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

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

 
Top of section

Specifying submission elements

The submission element defines:

Procedure 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:

    1. Click edit namespace list.

    2. Select the namespaces you want to include. Use Shift to select a contiguous group and Ctrl-Shift to select multiple non-contiguous items.

    3. 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:

    1. Click Edit CDATA element list.

    2. In the Edit CDATA item list dialog, click Add.

    3. Type the name in the Add List dialog.

    4. Click OK.

    5. Click OK.

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

 
Top of section

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.

Procedure To create a bind element:

  1. Select bind.

  2. Right-click and select Add item.

Procedure To delete a bind element:

  1. Select the bind element.

  2. Right-click and select Delete item.

Procedure 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    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    For more information, see Format

Specifying model item properties

You can specify these Model Item properties like this:

Model item property

Description

Readonly

Users are not allowed to change the data. Any form controls bound to a read-only node are not enabled.

To make a node readonly:

  1. In the Property Inspector, choose readonly.

  2. Create an XPath expression that evaluates to a boolean, or change the value to true().

Required

Users are required to supply a value. Any form controls bound to a required node will generate a submit error if a value is not supplied.

To make a node required:

  1. In the Property Inspector, choose required.

  2. Create an XPath expression that evaluates to a boolean, or change the value to true().

Relevant

Specifies whether a node is visible. Form controls bound to nonrelevant nodes are disabled or not visible.

If you make a nonrelevant node required, the required property is ignored.

To make a node nonrelevant:

  1. In the Property Inspector, choose relevant.

  2. Create an XPath expression that evaluates to a boolean, or change the value to false().

Calculate

Specifies a calculation that defines the value of the node.

To create a calculation on a node:

  1. In the Property Inspector, choose Calculate.

  2. In the XPath Navigator, construct the calculation.

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

Constraint

Specifies a boolean expression that when false causes the associated model item to be regarded as valid. (The converse is not necessarily true.)

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.

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

    frmAlertLiteralText

  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.

 
Top of page

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:

 
Top of section

About the Event Editor

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

frmEventEditor

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.

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

    XFormsEventEditorLaunch

    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.

Procedure To create an event handler:

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

    frmEventMain

  2. Click the Create a new event handler icon.

    frmNewEventIcon

    The Create Event Handler for Element dialog displays:

    frmEventType

  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.

Procedure To specify XForms Actions for an event handler:

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

    frmNewActionCreate

  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    For more information about Action properties, see the XForms specification.

Procedure To delete an action:

  1. Select the action from the Action List.

  2. Click the delete icon.

    frmNewActionDelete

Procedure To delete an event handler:

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

  2. Click the delete icon.

    frmNewActionDelete

 
Top of section

XForms Actions Reference

Click an action to display complete information.

Action

Action

Delete

Reset model

Dispatch

Send instance data

Insert

Set Focus

Load link

Set index in repeat

Message

Set value

Rebuild, Recalculate, Refresh, and Revalidate model

Toggle select case in switch

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.

XFormsDeleteActionAttributes

Complete the attributes as follows:

Attribute

What to do

Notes

Use XPath expression

Choose Use XPath expression to specify an XPath expression that identifies the data node to delete.

You can type the expression in the choice box, or click the ellipsis to launch the XPath Navigator.

The Event Editor constructs an <xforms:action> with a nodeset definition.

Model ID

Optional.

Choose a Model ID from the choice box.

A Model ID is only needed when:

  • You choose Use XPath expression.

  • The form references multiple models containing instance data elements of the same name.

Use binding

Choose Use binding to specify an existing bind expression that identifies the data node to delete, then choose a binding ID from the choice box.

The choice box is only populated if you've defined a binding element and specified IDs for them in the Model tab.

Location

Specify the location of the data node to delete via an XPath expression.

You can type the expression in the choice box, or click the ellipsis to launch the XPath Navigator.

Valid expressions include:

  • last()—specifies the last item in the nodeset.

  • 1—specifies the first item in the nodeset.

  • index()—Refers to the position of the current selection in the specified repeat.

Dispatch

Description

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

Attributes

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

XFormsDispatchAttributes

Complete the attributes as follows:

Attribute

What to do

Notes

Send event

Choose an event to dispatch.

If the event is not listed, you can type it in the choice box.

target

Choose the ID of the element the event is dispatched to.

The choice box is populated with elements for which you have defined IDs.

Valid target elements include:

  • Model elements

  • Instance elements

  • Action elements

  • Submission elements

  • Form controls

bubbles

Check if the dispatched event bubbles.

For custom events only.

Optional.

cancelable

Check if the dispatched event can be cancelled.

For custom events only.

Optional.

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:

XFormsInsertActionAttributes

Complete the attributes as follows:

Attribute

What to do

Notes

Use XPath expression

Click Use XPath expression to specify an XPath expression that identifies the data node to insert.

You can type the expression in the choice box, or click the ellipsis to launch the XPath Navigator.

Model ID

Optional.

Choose a Model ID from the choice box.

A Model ID is only needed when:

  • You click Use XPath expression.

  • The form references multiple models containing instance data elements of the same name.

Use binding

Click Use binding to specify an existing bind expression that identifies the data node to delete, then choose a binding ID from the choice box.

The choice box is only populated if you've defined a binding element and specified an ID for it (in the Model tab).

Location

Specify the location for the insert, within the data node, via an XPath expression.

You can type the expression in the choice box, or click the ellipsis to launch the XPath Navigator.

Valid expressions include:

  • last()—specifies the last item in the nodeset.

  • 1—specifies the first item in the nodeset.

  • index()—specifies the position of the current selection in the specified repeat.

Position

  • Choose Before to insert the new node before the node specified by the location attribute.

  • Choose After to insert the new node after the node specified by the location attribute.


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:

XFormsLoadLink

Complete the attributes as follows:

Attribute

What to do

Notes

Data node

Choose to specify a data node that resolves to a URI.

The URI must include the URL scheme such as HTTP or HTTP.

Choose Use XPath expression to specify the URI via an an XPath expression that resolves to a URI.

You can type the expression, or click the ellipsis to launch the XPath Navigator.

A Model ID is only needed when:

  • You click Use XPath expression.

  • The form references multiple models containing instance data elements of the same name.

Click Use binding to specify an existing bind expression that resolves to a URI.

The choice box is only populated if you've defined a binding element and specified an ID for it in the Model tab.

URI

Choose when you want to manually specify the URL.

The URI must include the URL scheme such as HTTP or HTTPS.

For example:

  http://www.novell.com

New window

Choose if successful navigation should launch the URL in a new window.


Current window

Choose if successful navigation should launch the URL in the current window.


Message

Description

Launches a modal, modeless, or ephemeral message box.

Attributes

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

XFormsMessageAction

Complete the attributes as follows:

Attribute

What to do

Notes

Display Message

Choose one:

Inline text

Use for simple, static messages.

Type the message you want displayed in the text box.

URI

Use to display the contents of the file at the specified URL.The URL is invoked and the raw text is displayed in an alert box.

For example:

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

TIP:   You might use this as an alternate way of storing (and localizing) error messages; the URL could even pass arguments to a CGI script or a servlet to fetch localized messages.

Data node

Displays a message stored in an instance data node.


Expression

Use to construct complex inline text messages. Constructs an XForms output element as a child of the xforms:message element.

For example:

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

Message level

Choose one:

Modal

Blocks user input to all other windows until the user dismisses the message.

Modeless

Allows users to work with other windows without having to respond to the message.

Ephemeral


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    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:

XFormsRecalculateAction

Complete the attributes as follows:

Attribute

What to do

Notes

Model ID

Choose the Model ID from the choice box.

This is the model that will receive the event.

Reset model

Description

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

For more information    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:

XFormsResetActionAttributes

Complete the attributes as follows:

Attribute

What to do

Model ID

Choose the ID of the Model you want reset

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:

XFormsSendInstanceAction

Complete the attributes as follows:

Attribute

What to do

Notes

Submission ID

Choose a submission ID

Submission elements are defined in the Model tab.

The choice box is only populated when a Submission element is created and given an ID.

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:

XFormsSetFocusAction

Complete the attributes as follows:

Attribute

What to do

Notes

Control ID

Choose a Control ID from the choice box.

You can define a Control ID in the Property Inspector (in the Form tab).

The choice box is only populated when control elements are named in the Property Inspector.

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:

XFormsSetIndexAction

Complete the attributes as follows:

Attribute

What to do

Repeat element

Choose a repeat element from the choice box.

Item index

Specify an XPath expression that defines index

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:

XFormsSetValue

Complete the attributes as follows:

Attribute

What to do

Notes

Data node

Choose one to specify the data node whose value you want to set.


Use XPath expression—to specify an XPath expression.

You can type the expression in the choice box, or click the ellipsis to launch the XPath Navigator.

A Model ID is only needed when the form references multiple models containing instance data elements of the same name.

Use binding—to specify an existing bind expression.

The choice box is only populated if you've defined a binding element and specified an ID for it in the Model tab.

New Value

Choose one:


Inline text—to specify static values.

For example:

  This is a test value.

Expression—to construct dynamic values based on user input or other elements not known at design time.

For example:

  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:

XFormsToggle

Complete the attributes as follows:

Attributes

What to do

Notes

Case to select

Select the case ID from the choice box.

The choice box is only populated if you've defined a Switch element.

 
Top of section

Customizing event handlers

Procedure To customize event dispatching:

  1. Access the Advanced Options dialog by:

  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.

 
Top of page

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:

Use this tool

To test this

XForms preview

Event and data processing

XHMTL component look and feel

View Form in Browser

The look and feel of all components on the page

 
Top of section

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.

Procedure To use XForms Preview:

  1. Open the form.

  2. Choose the XForms Preview tab.

    The form is rendered and is available for interaction:

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

 
Top of section

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.

Procedure 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:

    frmViewForminBrowser

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

Procedure 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:

    frmApplyPortalTheme

  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.

Procedure 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:

    frmSetFontOverride

  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.

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