The form element is the root element of any ECHO Forms document. This attribute defines the target namespace of the form which is the namespace that all the user interface controls are in. This namespace is important when referring to controls imported from other ECHO Forms documents. See Reference Controls for more information on importing controls. The model element contains the instance and allows for extensibility to ECHO Forms. The instance represents both a model of the data that is the result of an ECHO Form as well as initial values for the model. There should be only one element inside the instance. The element in the instance should be valid such that if it were copied into its own document it would represent a valid XML document. This means that the element should define all namespaces and prefixes required for it and its sub elements. ECHO Forms is created such that it is extensible. Extensions are things that may be processed by a client or different parts of ECHO but may not apply to every use of ECHO Forms. An extension has a QName to identify it and can contain any XML not in the ECHO Forms namespace. The user interface (UI) of ECHO Forms is described in the form using controls. Control types vary to support the collection of various types of information. ECHO Forms Documents can import other ECHO Forms documents registered in ECHO. Import statements have two parts, a name and owner guid. The owner guid indicates the owner of the ECHO Forms document. The name indicates the file name of the ECHO Forms document.

A group combines together other controls to show they belong together. A group is often displayed as a bounding box with a label. This shows the user that the elements of the group are part of a single unit.

Common Component Variations

The ref attribute is optional for a group. It can not reference an attribute.

Types Supported: string, double, dateTime, long, int, short, boolean

The input control allows free-form input from the user. The client should attempt to provide an accurate rendering of the control for the given data type. For example, for a boolean type a checkbox should be used. For a dateTime type, a date picker should be used.

Types Supported: string, double, dateTime, long, int, short

This form control allows the user to make one or multiple selections from a set of choices. A select control uses an attribute to indicate if it is a single or multiple select. A select may also be open, which means that a user may type in a value and select it. In the case of an open select, the items in the instance which indicate selection may not be limited to the items in the original list of choices.

Common Component Variations

  • The ref attribute will refer to the root element which will hold the selected value elements. The name of the selected value elements is indicated with a specific attribute.
  • The required attribute indicates that at least one item must be selected. If the required attribute is false, an instance document with no selected items is valid. A constraint may be used to enforce a minimum number of selected items (for example, enforcing the selection of at least three items in a selection).
  • Computed Expression: No

The item child element defines the valid items that may occur in the selection. Each item element contains a value and label child elements. The label will be displayed to the user by the client application for each item. The value is the value that will occur in the model instance if the item is selected. Value must be of length greater than or equal to 1.

  • Computed Expression: No
  • Legal Values: ‘true’ or ‘false’
  • Default Value: false
  • Inheritance rules: None

The multiple attribute contains a Boolean value which indicates if the selection allows multiple items to be selected. If multiple selections are supported, the client must allow the user to select more than one item in the list of choices.

  • Computed Expression: No
  • Legal Values: any valid XML Schema NCName
  • Default Value: None
  • Inheritance rules: None

The valueelementname attribute contains an NCName which is the name of the child element of the ref element that will contain the selected values. This element should only occur in the instance document to provide default selections. If there is no default value for the select then the select element in the instance should not contain any children. The client application will add and remove instances of this element as the selection changes. The element will contain the value text of the selected item or items.

  • Computed Expression: No
  • Legal Values: ‘true’ or ‘false’
  • Default Value: false
  • Inheritance rules: None

The value attribute contains a Boolean value which indicates if the selection is open to user input. If the selection is open, the client must allow the user to enter values into the selection and select those new values. The editor for the value input should be type specific (for example, a date picker for the dateTime type). If the selection is not open, the client must ensure that only items in the list of choices are selected. If the user does not enter or select a value then there should be no value elements in the instance document for this select.

Types Supported: string, double, long, int, short

The secret control allows free-form input from the user. This control is identical to the input control with the following exceptions: it does not support the boolean or date types, user input must be obscured using an echo character such as a ‘*’. The secret control is normally used like an input control but for sensitive data such as user names or passwords.

Types Supported: string

The textarea control allows free-form input from the user. This control is similar to the input control, except that it allows for multi-line input. The textarea control only supports the string type.

Types Supported: double, dateTime, long, int, short

This form control allows selection from a sequential range of values. A range control has a minimum value, maximum value, and a step size. The selected value must be between the minimum and maximum and occur on a valid step increment. A client will normally render a range control as a slider, spinner, or up-down box. The client must use the type information in the range control to render the proper controls to the user. The user should be told of the minimum, maximum, and step size.

  • Computed Expression: No
  • Legal Values: any valid value in the type of the range
  • Default Value: None
  • Inheritance rules: None

The start attribute contains the minimum value of the range. This value is inclusive and must be the same type as the range control.

  • Computed Expression: No
  • Legal Values: any valid positive value in the type of the range except in the case of a dateTime, in which case the valid value is any positive integer
  • Default Value: None
  • Inheritance rules: None

The step attribute contains the amount that the range will move as the value is adjusted. The user is required to pick a value which occurs on a step based on the start value of the range. The client should attempt to force the user onto the step values to limit user error. The step value must be smaller than (end – start). In the case of a dateTime range type, the step value indicates the number of seconds.

  • Computed Expression: No
  • Legal Values: any valid value in the type of the range
  • Default Value: None
  • Inheritance rules: None

The end attribute contains the maximum value of the range. This value is inclusive and must be the same type as the range control.

Types Supported: string, double, dateTime, long, int, short, boolean, anyURI

Renders a value from the instance data, but provides no means for entering or changing data. It is used to display values from the instance. The output control can be used to display the value at a particular location in the instance by using a binding expression; it can also be used to display the result of evaluating an XPath expression by specifying the XPath expression to be evaluated via attribute value instead of ref. Note that attributes ref and value on element output are mutually exclusive. It is recommended when the type of “anyURI” is used that the client display the component as a clickable link.

Common Component Variations

  • The ref attribute is mutually exclusive with the value attribute.
  • The readonly attribute is ignored.
  • The required attribute is ignored.
  • Computed Expression: Yes
  • Legal Values: any XPath expression that returns a string value
  • Default Value: false
  • Inheritance rules: None

The value attribute contains an XPath expression that will be evaluated. The resulting string of the evaluation will be displayed. This attribute is mutually exclusive with the ref attribute. If the value attribute is used, the type attribute must be type string.

A repeat allows the definition of repeating structures such as points within a polygon. As grouping controls repeats can be nested to define multiple levels of repetition such as many polygons being entered each with many points. Repeat may be the most complex control for clients to handle. Clients must be able to allow the user to add or remove the repeated items.

Common Component Variations

The ref attribute is can not reference an attribute for a repeat. Ref in a repeat should reference the element to which the elements in the template should be added.

  • Computed Expression: No
  • Legal Values: Any XML in namespace other than ECHO Forms namespace
  • Default Value: None
  • Inheritance rules: None

Template is an element in repeat that is similar to instance in the model in that it can contain any XML and defines a model for the controls in the repeat. The template is used as a template for creating new elements to add as children to the node that ref points to. Template can contain only one root element. All of the children of a repeat reference a node in the repeats template.

  • Computed Expression: No
  • Legal Values: Any valid XML Schema int
  • Default Value: 0
  • Inheritance rules: None

The minItems attribute contains the minimum number of items that may appear in the repeat. The items refer to the instances of the template. The minItems attribute can be used to force a lower limit number of instances in the repeat before it is considered valid. It is recommended that if the repeat contains the minimum number of items, a client should not allow the user to remove any more items. Setting the minItems and maxItems to the same value creates a closed repeat where items cannot be added or removed, but simply edited. The model instance in the form must have enough items in the repeat to satisfy this constraint.

  • Computed Expression: No
  • Legal Values: Any valid XML Schema int
  • Default Value: Max integer
  • Inheritance rules: None

The maxItems attribute contains the maximum number of items that may appear in the repeat. The items refer to the instances of the template. The maxItems attribute can be used to force an upper limit number of instances in the repeat before it is considered invalid. It is recommended that if the repeat contains the maximum number of items, a client should not allow the user to add any more items. Setting the minItems and maxItems to the same value creates a closed repeat where items cannot be added or removed, but simply edited. The model instance in the form must have fewer items in the repeat to satisfy this constraint.

Typed controls are strongly typed using XML Schema types. These types indicate the format as well as the valid values that may occur in the instance document.
  • Computed Expression: No
  • Legal Values: a QName of any supported XML Schema type
  • Default Value: None

The type attribute indicates the type of the data in the instance document. Clients can also use the type information to customize the control by rendering it differently for each supported type. The type attribute is required on all typed controls unless otherwise noted by the control.

A constraint child element specifies a predicate that needs to be satisfied for the associated instance data node to be considered valid. A control can have any number of constraints which are evaluated in the order that they appear. Because all the constraints must be satisfied, multiple constraints are ‘and-ed’ together. A constraint contains either a regular expression pattern or an XPath expression and an alert message.
  • Computed Expression: Yes
  • Legal Values: any XPath expression that returns a boolean value
  • Default Value: None
  • Inheritance rules: None

A xpath child element is a an XPath expression that must evaluate to true to satisfy the constraint. The XPath may contain new line and tab characters to support readability. New line and tab characters should be replaces with a space character before evaluating the XPath.

  • Computed Expression: No
  • Legal Values: any regular expression compatible with Perl 5
  • Default Value: None
  • Inheritance rules: None

A pattern child element is a regular expression that must match the node data to satisfy the constraint. The pattern will be applied to the un-encoded string value of the data node. Therefore XML elements in the value will be un-escaped, however if a pattern is applied to a xsd:dateTime for example, the string will represent the schema encoded dateTime.

  • Computed Expression: No
  • Legal Values: any xsd:string. It is recommended that a single, short sentence be used.
  • Default Value: None
  • Inheritance rules: None

A alert child element is a message that will be displayed to the user if the constraint is not satisfied. This message should contain a description of how the user can satisfy the constraint. For example, a password constraint alert may say, “Your password must be at least 8 characters and contain numbers and letter.” It is recommended that the client display this message in a noticeable means such as using bright colors or a notification dialog.

The selectref reference control indicates that the control referenced should replace this reference control in the form. The selectref element behaves identically to controlref except that it can only refer to select controls. A selectref element can limit the number of items available for selection in the referenced select control. Therefore, using a selectref, it is possible to share common selections even if all the users of the select control do not support all the items in the original select.

If a selectref is required to contain all the items in the referenced select control, it is recommended that a controlref be used instead of repeating all the items in the referenced select.

Common Component Variations

Selectref has the same variations as controlref
  • Computed Expression: No

The item child element defines the valid items that may occur in the selection. Each item element contains a value and label child elements. The label will be displayed to the user by the client application for each item. The value is the value that will occur in the model instance if the item is selected. All of the values specified must occur in the selection referenced. Therefore it is possible to only restrict a selection, but not to add new values to a referenced selection. If an item does not have a label, the label defined in the referenced select control item should be used.

The select item child element defines the valid items that may occur in the selection. Each item element contains a value and label child elements. The label will be displayed to the user by the client application for each item. The value is the value that will occur in the model instance if the item is selected. Value must be of length greater than or equal to 1. The label will be displayed to the user by the client application for each item. The value is the value that will occur in the model instance if the item is selected. Value must be of length greater than or equal to 1. A list of constraints.
  • Computed Expression: No
  • Legal Values: any xsd:string. It is recommended that a single, short sentence be used.
  • Default Value: None
  • Inheritance rules: Not inherited.

A help child element is a simple text element that contains a string that will be used as the help of the control. Although the client can choose the best way to associate the help with the control, the help should be a single, short sentence and is normally rendered as a tool tip or status bar message for the data portion of the control.

  • Computed Expression: Yes
  • Legal Values: any XPath expression that returns a boolean value
  • Default Value: true()
  • Inheritance rules: If the parent is not relevant then the children are not relevant as well.

The relevant attribute is used to indicate the relevance of a given control. If the control is relevant, the control should be displayed by the client and all other attributes should be evaluated (such as required and read only). If a control is not relevant, it should be hidden by the client but the instance should not be modified. When an instance document is submitted, any non-relevant nodes (the relevant XPath evaluates to false) must be removed from the instance. Due to a limitation in the specification, it is important to express all dependencies for a control when using a ref attribute.

  • Computed Expression: Yes
  • Legal Values: any XPath expression that returns a boolean value
  • Default Value: false()
  • Inheritance rules: Not inherited.

The required attribute indicates that the instance document must contain a value for the control before the form may be submitted. A value of false indicates that the instance may or may not contain a value for the control. Required is only evaluated if the control is relevant.

  • Computed Expression: Yes
  • Legal Values: any XPath expression that returns a boolean value
  • Default Value: false()
  • Inheritance rules: If a parent is read only then the children are read only as well.

The readonly attribute indicates if the instance data is read only or mutable. If the attribute evaluates to true, the client must prevent the user from modifying the instance data. Note that because readonly is a computed expression, it may evaluate to true at one time and false another time. Therefore depending on the XPath used, one cannot guarantee that the instance data may not have change at some point in its lifespan. Obviously this would not be the case with a consistent XPath such as ‘true()’.

Unlike relevant, readonly controls should be displayed to the user, however the user must not be able to edit the data.

HintTo prevent a user from ever modifying part of the instance do not create a control that references that node. Use the Output control if the data needs to be displayed to the user but never modified. ReadOnly is best used if a control’s read only status should change based on other values within the instance.

  • Computed Expression: Yes
  • Legal Values: any XPath expression that returns an element or attribute node
  • Default Value: None
  • Inheritance rules: See ECHO Forms Specification, section 4.5 XPath Context

The ref attribute is used to bind a control to a node in the instance document. If a control has a ref attribute, the XPath must be valid for the instance document in the form model. Therefore, all controls that have a ref in the form must have a node in the default model instance. The ref attribute is the key in linking the UI with the model in an ECHO Forms form.

Controls are described in XML and rendered by a client application. Different clients may need to render the controls in different ways. For example, in an HTML based application, multiple HTML controls may need to be used to render a single ECHO Forms control such as a date input. For more interactive clients, such as a thick client .NET application, a complex date picker may be used.

The controls are associated to the instance document using XPath. The controls will be populated with the values in the default instance, and will update the instance as the data is modified in the control. Many of the controls support strictly typed data and may be rendered differently by the client based on the data type.

The controls in the user interface section are listed linearly with no layout information. A client must keep the order of the controls when rendering the form in order to maintain the semantic meaning behind the position of the controls. A client may decide to split the controls into multiple columns in a table, or in multiple dialogs. This behavior is acceptable, as long as related elements are visually associated.

  • Computed Expression: No
  • Legal Values: anything of type xs:NCNAME
  • Default Value: None
  • Inheritance rules: Not inherited

The id attribute allows a control to have a specific name that it can be referenced by. This is useful for error messages or creating control references. The whole identifier for a control consists of its id and the targetNamespace of the form it’s in.

  • Computed Expression: No
  • Legal Values: any xsd:string value. It is recommended that only a few words be used. New line characters are not permitted.
  • Default Value: None
  • Inheritance rules: Not inherited

A label attribute contains a string that will be used as the label of the control. Although the client can choose the best way to associate the label with the control, the label should be a limited number of words and is normally placed on the left or top of the data portion of the control.

The controlref reference control indicates that the control referenced should replace this reference control in the form. Any attributes defined in the controlref element will replace those defined in the referenced control. All constraints defined in a controlref element will be appended to those of the referenced control. A controlref element may reference any control with an id attribute. If the control referenced is in a separate form, the other form must be imported using the standard ECHO Forms import element.

Common Component Variations

Common component attributes used in a controlref will replace those of the control referenced. In this way, it is possible to replace the relevant, required, label, and ref components of the referenced control. If a controlref does not define one of the common control attributes, the value defined on the referenced control should be used.

  • Computed Expression: No
  • Legal Values: any QName which refers to a defined control id
  • Default Value: None
  • Inheritance rules: Not inherited

The idref attribute is a QName which indicates the control to reference. The control referenced must be defined with the given id.

  • Computed Expression: No
  • Legal Values: any xsd:string value. It is recommended that only a few words be used. New line characters are not permitted.
  • Default Value: None
  • Inheritance rules: Not inherited

A label attribute contains a string that will be used as the label of the control. Although the client can choose the best way to associate the label with the control, the label should be a limited number of words and is normally placed on the left or top of the data portion of the control.