Skip to content

The Binds

Jump to bottom
Callum Newman edited this page Sep 24, 2024 · 3 revisions

Understanding bind in XForms

In XForms, the <bind> element connects the form controls (UI components) to the data instance, allowing you to define the structure and rules for data processing.

Placement of Binds

The <bind> elements are traditionally placed directly after the <instance> element. This structure ensures that all binds are linked to their corresponding instance fields and can enforce validation, constraints, and other behaviors on the data.

Example Bind

<bind id="dPublishDate" nodeset="dPublishDate" required="false()" type="string"/>
  • id: dPublishDate – This identifies the bind and links it to a control in the form.
  • nodeset: dPublishDate – This links the bind to the corresponding field in the instance.

Bind Attributes Explained

Each <bind> element can contain several attributes, which define how the data is processed and validated. Here's an explanation of the key attributes:

1. id

  • A unique reference that connects the bind to a form control.

2. nodeset

  • An XPath expression that links the bind to a value in the instance. It can reference a node or attribute in the XML instance.
  • Supports XPath expressions to dynamically reference parts of the XML structure.
  • Binds can be nested, allowing the nodeset value to be concatenated from parent binds.

3. required

  • An XPath expression that determines if the field is mandatory.
  • required="true()": The field is required.
  • required="false()": The field is not required (default if not specified).
  • required="/nodename[@myvalue='yes']": The field is required only if the XPath condition is met (e.g., nodename/@myvalue equals yes).

Note: The required attribute can evaluate complex XPath expressions that compare multiple fields and return true or false.

4. constraint

  • An XPath expression that enforces validation rules on the field.
  • Example constraints:
    • constraint="nodename/@value = ''": The field is valid only if nodename/@value is empty.
    • constraint="nodename/@value > '10'": The field is valid only if nodename/@value is greater than 10.
    • constraint="nodename/@value1 = nodename/@value2": The field is valid only if two values are equal.

Note: Remember to account for namespaces in your XPath expressions when working with XML instances.

5. calculate

  • Automatically computes the value of the field based on an XPath expression. It can derive values from other parts of the instance.
  • Example: calculate="tblContent/cContentName" – The field will be populated based on the content of the specified node.

6. type

  • Specifies the data type of the field. The most common types include:
    • string
    • float or number
    • date
    • email
    • xml-replace (for XML fragments)
    • imgVerification (for image verification scenarios)
    • fileUpload
    • format:RegExp (for validating input using regular expressions)
    • reValidateUser (for confirming a user’s password during sensitive operations)

Example: type="string" defines a field that expects a string value.

Special Type: reValidateUser

The reValidateUser type is used when a form requires the user to re-enter their password before performing a sensitive operation, such as deleting content. It validates the password against the currently logged-in user’s credentials.

Complete Example: Binding in XForms

<?xml version="1.0" encoding="utf-8"?>
<Content type="xform" name="EditContent">
	<model>
		<instance>
		</instance>
		<submission id="EditContent" action="" method="post" event="return form_check(this)"/>
		<bind nodeset="tblContent">
			<bind id="cContentHeadline" nodeset="cContentName" required="true()" type="string"/>

			<bind id="dPublishDate" nodeset="dPublishDate" required="false()" type="string"/>
			<bind id="dExpireDate" nodeset="dExpireDate" required="false()" type="string"/>
			<bind id="nStatus" nodeset="nStatus" required="true()" type="string"/>
			<bind id="cDescription" nodeset="cDescription" required="false()" type="string"/>
			<bind nodeset="cContentXmlBrief/Content">
				<bind id="cContentHeadline" nodeset="Headline" required="true()" type="string"/>
				<bind id="dPublishDate" nodeset="PublishDate" required="false()" type="string"/>
				<bind id="cContentStrapline" nodeset="Strapline" required="false()" type="string"/>
        <!--bind id="cContentHeadline" nodeset="Images/img[@class='thumbnail']/@alt" required="false()" type="string"/-->
				<bind id="cContentThumbnail" nodeset="Images/img[@class='thumbnail']" required="false()" type="xml-replace"/>
			</bind>
			<bind nodeset="cContentXmlDetail/Content">
				<bind id="cContentHeadline" nodeset="Headline" required="true()" type="string"/>
				<bind id="dPublishDate" nodeset="PublishDate" required="false()" type="string"/>
				<bind id="cContentStrapline" nodeset="Strapline" required="false()" type="string"/>
				<bind id="cContentThumbnail" nodeset="Images/img[@class='thumbnail']" required="false()" type="xml-replace"/>	
				<bind id="cContentDetail" nodeset="Images/img[@class='display']" required="false()" type="xml-replace"/>		
				<bind id="cContentBody" nodeset="Body" required="false()" type="string"/>
			</bind>
      <bind id="dPublishDate" nodeset="dPublishDate" required="false()" type="string"/>
		</bind>
	</model>


</Content>

This section illustrates how binds are used within a typical XForm, covering multiple nodesets and nested bindings.

This guide provides a concise and clear overview of the <bind> element in XForms, its attributes, and how to use it effectively in form definitions.

Clone this wiki locally