Dojo Made Easy

This chapter is from the book

XPages Extension Library: A Step-by-Step Guide to the Next Generation of XPages Components

Learn More Buy

This chapter is from the book

This chapter is from the book 

XPages Extension Library: A Step-by-Step Guide to the Next Generation of XPages Components

Learn More Buy

Dojo Extensions to the Edit Box Control

Many controls extend the Edit Box control, whether for storing text values, number values, or date/time values. These controls are not used in the TeamRoom database, so we will review the Extension Library demo database, which is available from OpenNTF. Specifically, we will review the Core_DojoFormControls.xsp XPage.

Dojo Text Box (xe:djTextBox)

The Dojo Text Box control is an excellent example of a control that appears to be simple but can provide functionality not available in the core Edit Box control. In most implementations, all that is required is to drag and drop it onto the XPage or custom control.

When you look at the properties available and compare them to the core Edit Box control, some differences become apparent. Table 5.1 describes the main properties that are standard across the Dojo widgets.

Table 5.1. Dojo Widget Properties

Table 5.2 describes the properties specific for the Dojo Text Box controls. On the All Properties panel of the Dojo Text Box, the data category contains the same properties as the Edit Box (xp:inputText) control. But a smaller subset of properties is listed under the basics category. Some of the options, including autocomplete, password, htmlFilterIn, and htmlFilter—visible on an Edit Box control—are not available for this control. Note that some properties like readonly and maxlength are camel case for the Dojo controls and become readOnly and maxLength on the Dojo Text Box control.

Table 5.2. xe:djTextBox Properties

The Dojo Text Box also offers some additional properties. Some properties, such as alt, tabIndex, title, waiRole, and waiState, are standard for the Dojo extended controls, always appearing under the accessibility category. WAI might be unfamiliar to some Domino developers who are not used to web development. WAI is an initiative by the World Wide Web Consortium (W3C) to ensure that websites follow accessibility guidelines. This has been extended for applications by Web Accessibility Initiative—Accessible Rich Internet Applications (WAI-ARIA), which differentiates applications from static web pages. It is not yet standard, but it is good practice. A full taxonomy of roles (http://www.w3.org/WAI/PF/GUI/roleTaxonomy-20060508.html) and states (http://www.w3.org/WAI/PF/adaptable/StatesAndProperties-20051106.html) is available on the W3C site. The good news is that even if you do not define the waiRole and waiState properties on the Dojo extended controls, default roles and states are added. But, if required, the properties are exposed to allow you to override the defaults.

Other properties are exposed that offer additional functionality over the Edit Box control or even the standard TextBox control in the Dojo toolkit. In the basics category, the maxLength property enables developers to ensure that users are restricted to a certain number of characters. This is triggered on key press, so rather than alerting users after they have left the field, the user physically cannot type more characters than you allow. However, bear in mind that if the field should include punctuation, decimal separators, and so on, each counts as one character. You can use the trim property to remove any leading or trailing spaces. It does not remove duplicate spaces within the string.

The dojo category is expanded from the Edit Box control with some additional Dojo properties: dragRestriction, intermediateChanges, and tooltip. These properties are standard for the Dojo widgets and may not be appropriate for all controls. For example, the tooltip property is used only for controls such as the Dojo Tab Pane, where the title property has a different function than applying hover text. The format category provides boolean properties lowercase, uppercase, and propercase to force case conversion. The formatting takes effect as soon as the user exits the field.

Some of the differences in the events category between the Edit Box control and the Dojo Text Box control are just minor. Properties like onfocus, onblur, onchange, and onclick become onFocus, onBlur, onChange, and onClick. It’s not a major difference, and indeed there is no difference in implementation. But there are a few additions. The mousing events are supplemented by onMouseEnter and onMouseLeave, ostensibly no different from onMouseOver and onMouseOut. A simple alert statement will show that the onMouseOver event is triggered before the onMouseEnter event. Likewise, onMouseOut is triggered before onMouseLeave.

Dojo Validation Text Box (xe:djValidationTextBox)

There are no prizes for guessing that the Dojo Validation Text Box control is similar to the Dojo Text Box control, except that it adds validation. All the properties we outlined on the Dojo Text Box control are available, including those for dynamically setting the value to lowercase, uppercase, or propercase and trimming the value.

However, the Dojo Validation Text Box is not, by default, mandatory. Initially, this sounds incomprehensible. What’s the point of the Dojo Validation Text Box if it’s not validated? But if we investigate a little further, we will come across the promptMessage property. This enables the developer to add a message for the user. At runtime, this is delivered to the user by default as a tooltip, as in Figure 5.6.

Figure 5.6. Dojo Validation Text Box promptMessage.

Basic validation is managed in the same way as for any other input control: by using the required property. But validation for the traditional Edit Box control is handled on the client or the server, as determined by the developer in the Application Properties or the administrator in the Server Settings. In the Dojo Validation Text Box, validation is always handled Client-Side, even if client validation is switched off in the Application Properties. That is because the Dojo Validation Text Box is a Dojo control, and Dojo validation runs Client-Side (because Dojo is a set of Client-Side JavaScript libraries). So as soon as the user tabs out of the field, the validation is triggered and the field is highlighted, as in Figure 5.7. As with the dijit. form.ValidationTextBox Dojo module, an error message in the invalidMessage property has no effect if the control just has the required property set to "true" but no other validation applied.

Figure 5.7. Dojo Validation Text Box error message.

But the Dojo Validation Text Box doesn’t just validate that a value has been entered. In the dojo-widget category, the regExp property takes as its value a regular expression, a standard web development validation notation that is designed to be agnostic of programming language. The regExpGen property can generate a regular expression using Client-Side JavaScript. Rather than researching and typing a regular expression, Dojo provides some prebuilt objects for validating standard regular expressions, such as dojo.regexp.realNumber and dojo.regexp.ipAddress. These can be found in files like dojo.number and dojox.validate, all of which extend dojo.regexp, the object that defines the function to validate against regular expressions. For example, Listing 5.6 takes the ipAddress function in dojox.validate.regexp.js, amending it only to expect no parameters. As a function in the regExpGen property, this code will validate that the user enters a valid IP address, without the need to work out or type in the relevant regular expression. As with traditional XPages validation, there is a default, but developers can also provide their own message, using the invalidMessage property.

Listing 5.6. Validating an IP Address

<xe:djValidationTextBox
   value="#{sessionScope.djValidationTextBox1}"
   invalidMessage="Please enter a valid ip address">
   <xe:this.regExpGen><![CDATA[// summary: Builds an RE that matches an
IP address
//
// description:
//  Supports five formats for IPv4: dotted decimal, dotted hex, dotted
octal, decimal, and hexadecimal.
//  Supports two formats for Ipv6.
//
// flags An object. All flags are boolean with default = true.
//    flags.allowDottedDecimal Example, 207.142.131.235. No zero
padding.
//    flags.allowDottedHex  Example, 0x18.0x11.0x9b.0x28. Case
insensitive. Zero padding allowed.
//    flags.allowDottedOctal Example,  0030.0021.0233.0050.  Zero
padding allowed.
//    flags.allowDecimal  Example,3482223595. A decimal number between
0-4294967295.
//    flags.allowHex  Example, 0xCF8E83EB. Hexadecimal number between
0x0-0xFFFFFFFF.
//      Case insensitive. Zero padding allowed.
//    flags.allowIPv6   IPv6 address written as eight groups of four
hexadecimal digits.
//    FIXME: ipv6 can be written multiple ways IIRC
//    flags.allowHybrid   IPv6 address written as six groups of four
hexadecimal digits
//      followed by the usual four dotted decimal digit notation of
IPv4. x:x:x:x:x:x:d.d.d.d

// assign default values to missing parameters
flags = {};
if(typeof flags.allowDottedDecimal != "boolean"){
flags.allowDottedDecimal = true; }
if(typeof flags.allowDottedHex != "boolean"){ flags.allowDottedHex =
true; }
if(typeof flags.allowDottedOctal != "boolean"){ flags.allowDottedOctal
= true; }
if(typeof flags.allowDecimal != "boolean"){ flags.allowDecimal = true;
}
if(typeof flags.allowHex != "boolean"){ flags.allowHex = true; }
if(typeof flags.allowIPv6 != "boolean"){ flags.allowIPv6 = true; }
if(typeof flags.allowHybrid != "boolean"){ flags.allowHybrid = true; }
// decimal-dotted IP address RE.
var dottedDecimalRE =
// Each number is between 0-255. Zero padding is not allowed.
    "((\\d|[1-9]\\d|1\\d\\d|2[0-4]\\d|25[0-5])\\.){3}(\\d|[1-
9]\\d|1\\d\\d|2[0-4]\\d|25[0-5])";

// dotted hex IP address RE. Each number is between 0x0-0xff. Zero
padding is allowed, e.g. 0x00.
var dottedHexRE = "(0[xX]0*[\\da-fA-F]?[\\da-fA-F]\\.){3}0[xX]0*[\\da-
fA-F]?[\\da-fA-F]";

// dotted octal IP address RE. Each number is between 0000-0377.
// Zero padding is allowed, but each number must have at least four
characters.
var dottedOctalRE = "(0+[0-3][0-7][0-7]\\.){3}0+[0-3][0-7][0-7]";

// decimal IP address RE. A decimal number between 0-4294967295.
var decimalRE =  "(0|[1-9]\\d{0,8}|[1-3]\\d{9}|4[01]\\d{8}|42[0-
8]\\d{7}|429[0-3]\\d{6}|" +
   "4294[0-8]\\d{5}|42949[0-5]\\d{4}|429496[0-
6]\\d{3}|4294967[01]\\d{2}|42949672[0-8]\\d|429496729[0-5])";

// hexadecimal IP address RE.
// A hexadecimal number between 0x0-0xFFFFFFFF. Case insensitive. Zero
padding is allowed.
var hexRE = "0[xX]0*[\\da-fA-F]{1,8}";

// IPv6 address RE.
// The format is written as eight groups of four hexadecimal digits,
x:x:x:x:x:x:x:x,
// where x is between 0000-ffff. Zero padding is optional. Case
insensitive.
var ipv6RE = "([\\da-fA-F]{1,4}\\:){7}[\\da-fA-F]{1,4}";

// IPv6/IPv4 Hybrid address RE.
// The format is written as six groups of four hexadecimal digits,
// followed by the 4 dotted decimal IPv4 format. x:x:x:x:x:x:d.d.d.d
var hybridRE = "([\\da-fA-F]{1,4}\\:){6}" +
    "((\\d|[1-9]\\d|1\\d\\d|2[0-4]\\d|25[0-5])\\.){3}(\\d|[1-
9]\\d|1\\d\\d|2[0-4]\\d|25[0-5])";

// Build IP Address RE
var a = [];
if(flags.allowDottedDecimal){ a.push(dottedDecimalRE); }
if(flags.allowDottedHex){ a.push(dottedHexRE); }
if(flags.allowDottedOctal){ a.push(dottedOctalRE); }
if(flags.allowDecimal){ a.push(decimalRE); }
if(flags.allowHex){ a.push(hexRE); }
if(flags.allowIPv6){ a.push(ipv6RE); }
if(flags.allowHybrid){ a.push(hybridRE); }
var ipAddressRE = "";
if(a.length > 0){
    ipAddressRE = "(" + a.join("|") + ")";
}
return ipAddressRE; // String]]></xe:this.regExpGen>
</xe:djValidationTextBox>

Alternatively, if developers already have a prexisting Client-Side JavaScript function to validate the value entered, the validatorExt property in the dojo-widget category provides an extension point to call the function. The beauty of this is that developers only need to enter a Client-Side JavaScript object that is a function; the XPage runs the validation in all the events that are appropriate. This speeds up development and minimizes the effort of refactoring.

By default, your validation triggers only when the user has finished editing the field. To trigger validation or other events with each key press, you can set intermediateChanges to true. (By default, it is false.)

On top of all this, the validator and validators properties still exist for core XPages validation. Overall, the Dojo Validation Text Box provides an extremely flexible mechanism for validating the control while maintaining the Dojo look and feel.

Two additional formatting properties are available: displayMessageExt and tooltipPosition. The tooltipPosition property defines the position relative to the field in which any tooltip messages will appear. With the displayMessageExt property, a developer can write a Client-Side JavaScript function to override the appearance of the prompts and validation error messages.

(GIR 0AA)|(((A[BL]|B[ABDHLNRSTX]?|C[ABFHMORTVW]|D[ADEGHLNTY]
|E[HNX]?|F[KY]|G[LUY]?|H[ADGPRSUX]|I[GMPV]|JE|K[ATWY]
|L[ADELNSU]?|M[EKL]?|N[EGNPRW]?|O[LX]|P[AEHLOR]|R[GHM]|S[AEGKL
MNOPRSTY]?|T[ADFNQRSW]|UB|W[ADFNRSV]|YO|ZE)[1-
9]?[0-9]|((E|N|NW|SE|SW|W)1|EC[1-4]|WC[12])[A-HJKMNPR-Y]|(
SW|W)([2-9]|[1-9][0-9])|EC[1-9][0-9]) [0-9][ABD-HJLNP-
UW-Z]{2})

Table 5.3 summarizes the additional properties of the Dojo Validation Text Box, extending those already covered under the Dojo Text Box.

Table 5.3. xe:djValidationTextBox Properties

Dojo Number Text Box, Dojo Currency Text Box (xe:djNumberTextBox and xe:djCurrencyTextBox)

The Dojo Number Text Box and Dojo Currency Text Box controls extend the Dojo Validation Text Box still further in relation to validating numeric values. All the validation methods we have covered are already available, although the required property is virtually redundant, because a blank value is translated to 0 on save. But the power of the Dojo Number Text Box lies in the xe:djNumberConstraints extension. It is a complex property comprising a variety of child properties, as can be seen in Figure 5.8. The significant property, as shown, is type. This determines the output format from the control, but because of an issue with Dojo, scientific is not yet supported. Similarly, the value currency and the related properties currency and symbol are only applicable for the Dojo Currency Text Box.

Figure 5.8. xe:djNumberConstraints.

The main strength of the xe:djNumberConstraints extension, whose properties are shown in Table 5.4, is enforcing appropriate data entry by the user. Percentages can be messy to enforce, handling the percentage sign if users do or do not enter it, manipulating the value for subsequent calculations, and so on. Setting type to percent gets around this by ensuring the user enters a number followed by the percentage sign, such as “50%”, which the control then converts to the decimal value “0.5”. Likewise, specifying a pattern or places can translate the value entered by the user into an expected format, such as with a certain number of leading zeros or decimal places. With use of min and max, the entered value can be validated against a range, with an appropriate message defined in the rangeMessage property, specific for these controls. See Figure 5.9.

Table 5.4. xe:djNumberConstraints Properties

Figure 5.9. Dojo Number Text Box, Dojo Number Spinner, and Dojo Currency Text Box.

The Dojo Number Text Box has one further property that is of particular benefit if the entered value is passed to a managed bean or another Java object. This is the javaType property. Anyone who has worked with managed beans will be aware that the value is sometimes handled as a java.util.Long, sometimes as a java.util.Double, but never consistently. It all depends on the value the user enters, which can be annoying. The javaType property enables developers to override the type of the value passed to your underlying Java object and ensure it is always an int, always a double, always a float, and so on. Table 5.5 summarizes these additional properties available for the Dojo Number Text Box and Dojo Currency Text Box.

Table 5.5. xe:djNumberTextBox and xe:djCurrencyTextBox Properties

Dojo Number Spinner (xe:djNumberSpinner)

The Dojo Number Spinner allows the user to either type in a number or scroll up and down through the range with the keyboard or the buttons provided on the right edge of the control. This control is an implementation of dijit.form.NumberSpinner and an extension of the Dojo Number Text Box with all the properties applicable to that control (so currency-related properties of the xe:djNumberConstraints extension are not applicable). The control provides two properties for managing the incremental steps of the spinner: smallDelta and largeDelta. By default, the implicit increments are 1 and 10 respectively, but this can be overridden as required. The smallDelta increment is used when the user clicks the buttons provided or uses the cursor up and down keys. To take advantage of the largeDelta increment, users need to click the Page Up or Page Down keys.

If you hold down one of the buttons or keys, the increments are repeated after half a second and subsequently applied quicker and quicker. The defaultTimeout property, expecting an integer in milliseconds, determines how long the user needs to hold down the key before the increment is repeated; by default, it is 500 milliseconds. You configure the degree to which the increments are sped up using the timeoutChangeRate property. Because this is 0.9, the increments are applied progressively quicker the longer the key or button is held down, until the maximum speed is reached. If you set it at 1.0, the increments are always applied at the same time interval, never increasing. A value of greater than 1.0 has no effect.

Table 5.6 summarizes the properties of the Dojo Number Spinner control.

Table 5.6. xe:djNumberSpinner Properties

Dojo Date Text Box and Dojo Time Text Box (xe:djDateTextBox and xe:djTimeTextBox)

The Dojo Date Text Box and Dojo Time Text Box controls extend the Dojo Validation Text Box control. However, like the Dojo Number Text Box, Dojo Currency Text Box, and Dojo Number Spinner, they have their own constraints complex property. For the Dojo Date Text Box and Dojo Time Text Box, the constraints complex property implements the xe:djDateTimeConstraints extension, as detailed in Table 5.7 and illustrated in Figure 5.10.

Table 5.7. xe:djDateTimeConstraints Properties

Figure 5.10. xe:djDateTimeConstraints.

The main one for the Dojo Date Text Box is the datePattern property, which allows developers to define the format of the date presented to the user in the Dojo Date Text Box. For example, dd-MM-yyyy overrides the locale format to show 16^th June 2011 as 16-06-2011, and dd MMM yyyy shows as 16 Jun 2011. Alternatively, the formatLength property can be used to choose one of four predefined date or time formats. If both are used, the datePattern property takes precedence.

The Dojo Time Text Box control also uses the xe:djDateTimeConstraints property. But unlike the Dojo Date Text Box, properties are surfaced to allow the developer to manage the display of the control. To control how many hours are shown, you can define the visibleRange property. The visibleIncrement property defines the labels presented to the user, and the clickableIncrement property defines the increment for each value the user can select. You define each property using the format THH:mm:ss, so a visibleIncrement of 30 minutes is T00:30:00, as in Figure 5.11. With datePattern for the Dojo Date Text Box, the timePattern property defines the format for the times displayed to the user and presented in the field. Therefore, a format of h:mm presents, for example, 9:00, 9:30, and so on.

Figure 5.11. Time Picker.