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

Composite Dojo Extensions

Some extension controls are available under the Dojo category that do not fit into the previous categories. Rather than extending core controls available, these controls add new functionality not previously available as controls in XPages.

As Listing 5.3 shows, the dijit.form.HorizontalSlider requires multiple HTML elements. In the same way, some of the Dojo controls are more complex. Sliders comprise multiple components for their implementation, whereas the Dojo Link Select and Dojo Image Select controls have complex properties to define the values.

Sliders

The beginning of this chapter covered adding a slider with traditional Dojo. The code was covered in Listing 5.4, where the slider comprised a div with an ordered list of labels and an onchange event passing the value to a hidden field via Client-Side JavaScript. The sliders in the Extension Library remove the necessity to use a div with an onChange event to store the value. Rather, the sliders themselves are bound directly to the field.

There are two types of sliders, the Dojo Horizontal Slider (xe:djHorizontalSlider) and the Dojo Vertical Slider (xe:djVerticalSlider), as Figure 5.16 shows. Although the properties for both are identical and shown in Table 5.10, you need to choose the relevant slider at development time.

Table 5.10. xe:djHorizontalSlider and xe:djVerticalSlider Properties

The values of the slider are controlled by four properties: defaultValue defines the initial starting value (if the field the control is bound to does not already have a value), whereas minimum and maximum define the bounds of the slider, and discreteValues defines the number of steps between the minimum and maximum. By default, whenever the user clicks on a part of the slider, that value is selected, and this is controlled by the clickSelect property. If set to false, this functionality is suppressed. Also, by default, there are buttons on either end of the slider for moving the current position. Again, these can be suppressed by setting the showButtons property to false.

Figure 5.16. Sliders.

Besides clicking on a position of the slider or using the buttons, you can use keyboard shortcuts to control the movement, like you did for the spinner controls. All four cursor keys can be used for both sliders: left (←) and down (↓) moving in one direction, right (→) and up (↑) moving in the other direction. Although the cursor keys can be used to increment in small amounts, Page Up and Page Down increment in larger amounts. The smaller increment is always one step on the slider, but the developer can override the larger increment—by default 2 steps—using the pageIncrement property. Furthermore, because the speed of increment could be controlled for the spinners, it can also be controlled for the sliders, by means of the slideDuration property. This is a value in milliseconds that the slider will take to move from one end of the slider to the other; by default, it is one second.

As with the traditional Dojo implementation, you can add labels. This comprises two further controls: the Dojo Slider Rule (xe:djSliderRule) for the markers and the Dojo Slider Rule Labels (xe:djSliderRuleLabels) for the actual labels. For both controls, two properties determine how many and where the rules appear: count and container. The container provides a ComboBox list of options, with all four options available regardless: topDecoration, leftDecoration, bottomDecoration, and rightDecoration. Obviously, you must choose the relevant container for the relevant slider; rightDecoration and leftDecoration are not applicable for the Dojo Horizontal Slider.

You can map styling to CSS classes for both controls. You can style the markers by using the ruleStyle property on the Dojo Slider Rule, whereas you can style the labels by using the labelStyle property on the Dojo Slider Rule Labels.

You can set a number of additional properties for the Dojo Slider Rule Labels. The minimum and maximum properties set the top and bottom level for the labels, and numericMargin can define how many labels to omit at either end of the label list. So setting the value to 1 omits 0% and 100% from a default Dojo Slider Rule Labels control. As this suggests, the default labels are percentages, running from 0% to 100%. But you can override this in two ways. You can pass an array of labels into the labels property or use the labelList property, as shown in Listing 5.15. This method is recommended over <li> tags because it supports localization.

Listing 5.15. Dojo Horizontal Slider

<xe:djHorizontalSlider
   id="djHorizontalSlider2"
   value="#{sessionScope.djSlider1}"
   maximum="100"
   minimum="0"
   style="margin: 5px;width:200px; height: 20px;"
   discreteValues="10"
   pageIncrement="3">
   <xp:this.converter>
      <xp:convertNumber
         integerOnly="true">
      </xp:convertNumber>
   </xp:this.converter>
   <xe:djSliderRuleLabels
      id="djSliderRuleLabels2"
      container="topDecoration"
      style="height:10px;font-size:75%;color:gray;"
      count="6"
      numericMargin="1">
   </xe:djSliderRuleLabels>
   <xe:djSliderRule
      id="djSliderRule5"
      container="topDecoration"
      style="height:5px;" count="6">
   </xe:djSliderRule>
   <xe:djSliderRule
      id="djSliderRule6"
      style="height:5px;"
      count="5"
      container="bottomDecoration">
   </xe:djSliderRule>
   <xe:djSliderRuleLabels
      id="djSliderRuleLabels5"
      container="bottomDecoration"
      style="height:10px;font-size:75%;color:gray;">
<xe:this.labelsList>
        <xe:djSliderRuleLabel
           label="green tea">
        </xe:djSliderRuleLabel>
        <xe:djSliderRuleLabel
           label="coffee">
        </xe:djSliderRuleLabel>
        <xe:djSliderRuleLabel
           label="red bull">
        </xe:djSliderRuleLabel>
     </xe:this.labelsList>   </xe:djSliderRuleLabels>
</xe:djHorizontalSlider>

Table 5.11 shows the properties for the Dojo Slider Rule and Dojo Slider Rule Labels.

Table 5.11. xe:djSliderRule and xe:djSliderRuleLabels Properties

Dojo Link Select (xe:djLinkSelect)

The Dojo Link Select control allows developers to group link options so that when one link is selected, the others are deselected. You can see this in action with the filter area of the All Documents page on the TeamRoom database. Here, for example, selecting All by Date not only selects that entry but deselects the default All link. Unlike the traditional link functionality, you can bind the Link Select to a field or scoped variable. In addition, you can trigger a wealth of events from the Link Select.

Despite having properties multipleTrim and multipleSeparator, the control allows only one value to be selected at any one time. You can define the available options in a number of ways. The All Documents page (allDocumentsFilter.xsp custom control) uses selectItem controls, but you can also use a selectItems control. As with the ComboBox and FilteringSelect controls covered earlier, there is currently no mechanism to add an xp:selectItem or xp:selectItems control from the palette. So you can use the core ComboBox or ListBox control to define the values; then you can cut and paste the code across from the core control to the Dojo control.

Alternatively, there are three dataProviders available. Those who are comfortable with Java may choose to use the beanValuePicker. The other options are the simpleValuePicker and the dominoViewValuePicker. The simpleValuePicker allows a developer to define a list of options as a string of label value pairs. The label values themselves are defined in the valueList property. You can define the separator between the label and the value using the labelSeparator property, and you can define the separator between values using the valueListSeparator property. The dominoViewValuePicker allows you to select the options from a view, by defining the databaseName and viewName properties. The labelColumn property defines the column from which the values will be picked. The value set when the label is clicked is pulled from the first column in the view. So Listing 5.16 shows a Dojo Link Select where the options are pulled from the AllStates view, showing the Names column. Figure 5.17 shows the resulting output. As you can see, the onChange event refreshes the computed field with the value whenever you select a new link.

Figure 5.17. Link Select with dominoViewValuePicker.

Listing 5.16. Link Select Control with dominoViewValuePicker

<xe:djextLinkSelect
   id="djextLinkSelect2"
   defaultValue="MA"
   value="#{viewScope.link3}">
   <xe:this.dataProvider>
      <xe:dominoViewValuePicker
         viewName="AllStates"
         labelColumn="Name">
      </xe:dominoViewValuePicker>
   </xe:this.dataProvider>
   <xp:eventHandler
      event="onChange"
      submit="true"
      refreshMode="partial"
      refreshId="computedField3">
   </xp:eventHandler>
</xe:djextLinkSelect>

Table 5.12 shows the pertinent properties for the Dojo Link Select control.

Table 5.12. xe:djLinkSelect Properties

Dojo Image Select

The Dojo Image Select control is similar to the Link Select in that it provides a group of links, or in this case images, only one of which can be selected. Again, it is bound to a field or scoped variable, with a default value that can be set. The images are defined using selectImage child controls of the imageValues property. Each selectImage has image and selectedImage properties, to define the images that appear when the link is deselected or selected. The selectedValue property defines the value that will be set when the image is clicked. In addition, properties are available for styling each image, both in its deselected state and its selected state. The example on the Core_FormControl.xsp XPage in the Extension Library Demo database, reproduced in Listing 5.17 and shown in Figure 5.18, shows buttons appropriate for a Calendar View control, although, as will be shown in Chapter 7, a slightly different method is used for the calendar view in the TeamRoom database.

Figure 5.18. Dojo Link Select for Calendar Picker.

Listing 5.17. Dojo Image Select for Calendar Picker

<xe:djextImageSelect
   id="djextImageSelect1"
   title="Select a value default is two days"
   value="#{viewScope.image1}"
   defaultValue="T">
   <xe:this.imageValues>
      <xe:selectImage
         selectedValue="D"

selectedImage="/.ibmxspres/.extlib/icons/calendar/1_Day_selected_24.
gif"

image="/.ibmxspres/.extlib/icons/calendar/1_Day_deselected_24.gif"
      imageAlt="One Day">
   </xe:selectImage>
   <xe:selectImage
      selectedValue="T"

selectedImage="/.ibmxspres/.extlib/icons/calendar/2_Days_selected_24.
gif"

image="/.ibmxspres/.extlib/icons/calendar/2_Days_deselected_24.gif"
         imageAlt="Two Days">
      </xe:selectImage>
      <xe:selectImage
         selectedValue="F"

selectedImage="/.ibmxspres/.extlib/icons/calendar/1_Work_Week_selected_
24.gif"

image="/.ibmxspres/.extlib/icons/calendar/1_Work_Week_deselected_24.gif"
         imageAlt="One Work Week">
      </xe:selectImage>
      <xe:selectImage
         selectedValue="W"

selectedImage="/.ibmxspres/.extlib/icons/calendar/1_Week_selected_24.
gif"

image="/.ibmxspres/.extlib/icons/calendar/1_Week_deselected_24.gif"
         imageAlt="One Week">
       </xe:selectImage>
       <xe:selectImage
          selectedValue="2"

selectedImage="/.ibmxspres/.extlib/icons/calendar/2_Weeks_selected_24.
gif"

image="/.ibmxspres/.extlib/icons/calendar/2_Weeks_deselected_24.gif"
         imageAlt="Two Weeks">
       </xe:selectImage>
       <xe:selectImage
          selectedValue="M"

selectedImage="/.ibmxspres/.extlib/icons/calendar/Month_selected_24.
gif"
image="/.ibmxspres/.extlib/icons/calendar/Month_deselected_24.gif"
         imageAlt="One Month">
       </xe:selectImage>
       <xe:selectImage
          selectedValue="Y"

selectedImage="/.ibmxspres/.extlib/icons/calendar/All_Entries_selected_
24.gif"

image="/.ibmxspres/.extlib/icons/calendar/All_Entries_deselected_24.gif
"
          imageAlt="All Entries">
       </xe:selectImage>
  </xe:this.imageValues>
  <xp:eventHandler
    event="onClick"
    submit="true"
    refreshMode="partial"
    refreshId="computedField3">
  </xp:eventHandler>
</xe:djextImageSelect>

Table 5.13 details the additional properties available for the Dojo Image Select control.

Table 5.13. xe:djImageSelect Properties