Home > Articles > Web Development

  • Print
  • + Share This
This chapter is from the book

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

Property

Description

clickSelect

Defines whether the user can change the value by clicking on a position on the bar in addition to dragging the slider.

discreteValues

Defines the number of discrete values between the minimum and maximum values.

maximum

Defines the maximum value for the slider.

minimum

Defines the minimum value for the slider.

pageIncrement

Defines the number of increments applied to the slider when the user clicks the Page Up or Page Down button.

showButtons

Defines whether buttons are shown to move the slider.

slideDuration

Defines the number of milliseconds it takes to move the slider from 0% to 100%; it is 1000 milliseconds by default.

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

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

Property

Description

count

Defines how many markers or labels should appear.

labels

Allows the developer to write a Client-Side JavaScript expression to define the labels. This property is available only for the Dojo Slider Rule Labels.

labelsList

Allows the developer to define a localizable set of labels. This property is available only for the Dojo Slider Rule Labels.

maximum

Defines the maximum position for the labels. This property is available only for the Dojo Slider Rule Labels.

minimum

Defines the minimum position for the labels. This property is available only for the Dojo Slider Rule Labels.

numericMargin

Defines the number of labels to omit from either end of the label list. This property is available only for the Dojo Slider Rule Labels.

container

Defines where in relation to the slider line the markers or labels should appear.

ruleStyle

Defines the styling for the markers.

labelStyle

Defines the styling for the labels and is available only for Dojo Slider Rule Labels.

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

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

Property

Description

dataProvider

Provides the options for the Dojo Link Select as an xe:simpleValuePicker, xe:dominoViewValuePicker, or xe:beanValuePicker.

firstItemStyle

Defines styling for the first link.

firstItemStyleClass

Defines the class to be applied to the first link.

itemStyle

Defines styling for the intermediate links.

itemStyleClass

Defines the class to be applied to the intermediate links.

lastItemStyle

Defines styling for the last link.

lastItemStyleClass

Defines the class to be applied to the last link.

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

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

Property

Description

image

Defines the image shown when this image is not selected.

imageAlt

Defines the alt text to appear when the user hovers over the image.

selectedImage

Defines the image shown when this image is selected.

selectedStyle

Defines styling to be applied when this image is selected.

selectedStyleClass

Defines the class to be applied when this image is selected.

selectedValue

Defines the value to pass when this image is selected.

style

Defines styling to be applied when this image is not selected.

styleClass

Defines the class to be applied when this image is not selected.

  • + Share This
  • 🔖 Save To Your Account