- What Is Dojo?
- Default Dojo Libraries Using Dojo Modules in XPages
- Dojo Modules and Dojo in the Extension Library
- Dojo Extensions to the Edit Box Control
- Dojo Extensions to the Multiline Edit Box Control
- Dojo Extensions to the Select Control
- Dojo Extensions to Buttons
- Composite Dojo Extensions
- Dojo Effects Simple Actions
- Conclusion
This chapter is from the book
This chapter is from the book
This chapter is from the book
Default Dojo Libraries Using Dojo Modules in XPages
Before Domino 8.5.2, incorporating Dojo modules into XPages was challenging because many controls did not have a dojoType attribute. The only way to implement Dojo on an EditBox, for example, was to apply it programmatically. So in addition to the core control client side, JavaScript was required to trigger on load. Listing 5.1 demonstrates this programmatic implementation of the dijit.form.ValidationTextBox. Lines 1 to 4 show the core Edit Box control. Line 6 then begins an Output Script control, triggering XSP.addOnLoad() in line 16. The addOnLoad() calls a function that generates a new dijit.form.ValidationTextBox on line 9 adding various attributes. Line 13 adds the parameter to the new function, which applies the Dojo module to the Edit Box control.
Listing 5.1. Programmatic Implementation of dijit.form.ValidationTextBox
1 <xp:inputText
2 id="response"
3 value="#{ansDoc.response}">
4 </xp:inputText>
5
6 <xp:scriptBlock
7 id="scriptBlock1">
8 <xp:this.value><![CDATA[var convertInput = function() {
9 new dijit.form.ValidationTextBox(
10 {name:"#{id:response}",
11 required: true,
12 promptMessage: "Please complete the field"},
13 XSP.getElementById("#{id:response}")
14 );
15 };
16 XSP.addOnLoad(convertInput);
17 ]]></xp:this.value>
18 </xp:scriptBlock>
There is no reason you cannot use programmatic conversion of a core control to a Dojo module, if applicable. But with Domino 8.5.2, it became possible to declaratively convert the control thanks to the addition of the dojoType attribute to a variety of core controls. So for the Edit Box control, for example, in Domino 8.5.2 a Dojo panel was added and dojoType and dojoAttributes properties appeared on the All Properties panel, as shown in Figure 5.2. Not only is this easier to implement, but text strings entered as Dojo attribute values are picked up if localization is required and turned on for an application.
)
Figure 5.2. Dojo panel on Edit Box control.
Before digging into the Extension Library, let’s review several examples of implementing Dojo in XPages. Any developer who has used Dojo modules in XPages is aware of the steps required, ingrained quite probably by forgetting one of the steps at one time or another. The first critical step is to set dojoParseOnLoad and dojoTheme attributes to "true", as shown in lines 4 and 5 of Listing 5.2. The former tells the browser that after loading it needs to convert all content with a dojoType property; the latter tells the browser to load the relevant theme for styling all Dojo widgets (or dijits). The final step is to add as resources on the XPage any Dojo modules referenced on the page in a dojoType property.
Listing 5.2. dojoParseOnLoad and dojoTheme
1 <?xml version="1.0" encoding="UTF-8"?> 2 <xp:view 3 xmlns:xp="http://www.ibm.com/xsp/core" 4 dojoParseOnLoad="true" 5 dojoTheme="true"> 6 7 </xp:view>
Of course, you can perform all this on either an XPage or a Custom Control, but for simplicity, the reference will only be made to XPages. To provide a more appropriate comparison with the Extension Library controls, the examples in the sections that follow focus on declarative implementations of Dojo modules.
Simple Dojo Example: dijit.form.ValidationTextBox
The Dojo modules applied to an Edit Box are among the simplest implementations of Dojo. The dijit.form.ValidationTextBox is a simple extension to the Edit Box, which adds Client-Side validation with a styling consistent with other dijits to offer immediate validation and a prompt message. It has a number of Dojo attributes, some of which you can see in Listing 5.3. Figure 5.3 shows the resulting output. There is a host of printed and online documentation of Dojo (for examples, see the Dojo Toolkit website http://dojotoolkit.org/reference-guide/index.html). This book will not seek to exhaustively reproduce a glossary of the Dojo attributes and what they do.
)
Figure 5.3. dijit.form.ValidationTextBox.
Listing 5.3. dijit.form.ValidationTextBox
<xp:this.resources>
<xp:dojoModule
name="dijit.form.ValidationTextBox">
</xp:dojoModule>
</xp:this.resources>
<xp:inputText
id="inputText1"
value="#{viewScope.validationBox}"
dojoType="dijit.form.ValidationTextBox">
<xp:this.dojoAttributes>
<xp:dojoAttribute
name="required"
value="true">
</xp:dojoAttribute>
<xp:dojoAttribute
name="promptMessage"
value="Please complete this field">
</xp:dojoAttribute>
</xp:this.dojoAttributes>
</xp:inputText>
Defining Dojo modules and attributes is made a little challenging because there is no type-ahead or other context-sensitive help to advise on the Dojo modules available for use. There is also no validation of the correct naming conventions for the modules or validation of additional resources that need to be included. But this is to provide developers with the flexibility to take advantage of new releases of Dojo at the earliest opportunity and develop their own Dojo modules. For developers who are comfortable with the attributes available, this is not a problem; however, novice developers might find the size of the Dojo toolkit daunting.
Dojo Example for Slider
Some dijits are more involved than just setting a Dojo type and attributes to a Core control. A good example of this is the slider. There are actually two types of sliders: dijit.form.HorizontalSlider and dijit.form.VerticalSlider. The implementations are similar, so we shall just cover the HorizontalSlider.
As with dijit.form.ValidationTextBox, the slider is an input control, so you need to store the value in an Edit Box control (or, in most implementations, a Hidden Input control). However, you cannot directly attach the slider to the Edit Box. Instead, you apply the Dojo styling to a div and add an onchange event to pass the value to the Edit Box. Although the XPages Div control has dojoType and dojoAttributes properties, it does not have an onchange event, so it is easier to use an HTML div.
Further code is required to apply labels to the horizontal slider. You must apply an additional Dojo module to an HTML ordered list, dijit.form.HorizontalRuleLabels. Listing 5.4 shows the combination of XPage and HTML markup used to create a horizontal slider, which allows the user to select a value (in multiples of 10) within a range of 0 and 100, showing labels at increments of 20. The code required is rather extensive for a simple slider. Figure 5.4 shows the resulting output.
)
Figure 5.4. dijit.form.HorizontalSlider.
Listing 5.4. dijit.form.HorizontalSlider
<xp:this.resources>
<xp:dojoModule
name="dijit.form.HorizontalSlider">
</xp:dojoModule>
<xp:dojoModule
name="dijit.form.HorizontalRuleLabels"> </xp:dojoModule>
</xp:this.resources>
<div
id="horizontalSlider"
dojoType="dijit.form.HorizontalSlider"
value="50"
minimum="0"
maximum="100"
discreteValues="11" style="width:500px"
showButtons="false"
onChange="dojo.byId('#{id:horizontalHolder}').value =
dijit.byId('horizontalSlider').value">
<ol
dojoType="dijit.form.HorizontalRuleLabels"
container="bottomDecoration">
<li>0</li>
<li>20</li>
<li>40</li>
<li>60</li>
<li>80</li>
<li>100</li>
</ol>
</div>
<br />
<xp:inputText
id="horizontalHolder"
value="#{viewScope.horizontalSlider}"
defaultValue="50">
</xp:inputText>
Dojo Themes
All the dijits are styled according to a theme. The theme is defined on the XPages tab in the Application Properties, accessed from designer, using the Application Theme dialog list, as in Figure 5.5. The OneUI and Server Default themes use tundra by default. If the property Use runtime optimized JavaScript and CSS resources at the bottom of this tab is checked, a single aggregated stylesheet is delivered to the browser. This includes the following stylesheet:
/xsp/.ibmxspres/dojoroot-1.6.1/dijit/themes/tundra/tundra.css
In addition, the tundra theme is applied to the body tag, so the output HTML is <body class="xsp lotusui tundra">.
)
Figure 5.5. XPages tab of Application Properties in Domino Designer.
Dojo provides three other themes: nihilo, soria and, since Dojo 1.5.0, claro. Implementing these themes is just a matter of including the relevant stylesheets and applying the style to the body tag. The former is straightforward in XPages, the latter a little more involved. Within an XPage, you are limited on the attributes you can manipulate. However, via a custom theme, you can apply the Dojo theme to the body tag and reference the relevant stylesheets. If an application is not currently using a theme, just create a new Theme design element, found under the Resources category in the Application pane.
You can insert the code in Listing 5.5 between the theme tags. Lines 1 through 5 include the Dojo-themed stylesheet. Lines 8 through 14 apply the Dojo theme to the ViewRoot control, which becomes the body tag when the web page is loaded. Note in particular the inclusion in lines 2 and 8 of dojoTheme="true". By adding this, the logic checks whether the developer has set dojoTheme to "true" on the XPage or CustomControl. If the developer has set dojoTheme to "true", the stylesheet is loaded and the class is applied. If not, the stylesheet is not loaded and the class is not applied. To use soria or claro, just replace the three instances of nihilo with the relevant theme name.
Listing 5.5. Applying a Dojo Theme
1 <!— Include Dojo stylesheet —> 2 <resource dojoTheme="true"> 3 <content-type>text/css</content-type> 4 <href>/.ibmxspres/dojoroot/dijit/themes/nihilo/nihilo.css</href> 5 </resource> 6 7 <!— Add style to body element —> 8 <control dojoTheme="true"> 9 <name>ViewRoot</name> 10 <property mode="concat"> 11 <name>styleClass</name> 12 <value>nihilo</value> 13 </property> 14 </control>