- 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
Dojo Effects Simple Actions
The inclusion of Dojo within the Extension Library extends beyond controls for storing user-entered content. Some commonly used Dojo effects have also been added, implemented as Simple Actions. So you can easily add them to buttons, links, or anything else that has an event. These simple actions add animations to a form, to enhance the user experience.
So, for example, you can use a Dojo effect to fade in or wipe in helper text beside a field when the user clicks into it, and fade out or wipe out when the user exits the field. And because all the Dojo effects run Client-Side, there is no performance hit of round-tripping to the server.
Dojo Fade and Wipe Effects
The fade or wipe effects—either in or out—have additional properties that can be set. The node property is the component to be faded/wiped, a Server-Side component ID, as can be seen from Figure 5.19. The var property, as elsewhere, is a variable name the function uses to play the Dojo effect. You cannot reference it elsewhere on the XPage via Client-Side JavaScript, because it is scoped only to the eventHandler.
)
Figure 5.19. Dojo Fade In Effect.
The duration property defines how long in milliseconds the effect takes to run, whereas the easing property takes a function that will handle how the effect runs, such as accelerating the rate with which the node fades in. You can write this function from scratch, as on the Core_DojoEffects.xsp XPages Extension Library Demo database, or as a predefined function, such as those in the dojo.fx.easing object (see Listing 5.18).
Listing 5.18. Dojo Fade Out with dojo.fx.easing
<xp:this.resources>
<xp:dojoModule
name="dojo.fx.easing">
</xp:dojoModule>
</xp:this.resources>
<xp:button
value="Fade Out - Duration 2s"
id="button3">
<xp:eventHandler
event="onclick"
submit="false">
<xp:this.script>
<xe:dojoFadeOut
node="effect1"
duration="200"
easing="dojo.fx.easing.expoInOut">
</xe:dojoFadeOut>
</xp:this.script>
</xp:eventHandler>
Table 5.14 shows the main properties for the Dojo Fade and Wipe simple actions.
Table 5.14. xe:dojoFadeIn, xe:dojoFadeOut, xe:dojofxWipeIn, and xe:dojofxWipeOut Properties
|
Property |
Description |
|
duration |
Defines the duration the animation should take. |
|
easing |
Requires a Client-Side JavaScript function to define the rate of acceleration of the animation. |
|
node |
Defines the node to which the animation should be applied. |
|
var |
Defines a variable name under which the animation runs. |
Dojo Slide To Effect
The slide effect has all the properties of the fade and wipe effects but also two additional properties, top and left, for defining how far relative to the top and left of the screen the relevant node should be slid. You can set all the properties available with a specific value or calculate them via Server-Side JavaScript. The slide effect in Listing 5.19 shows how or why to use the attributes property: namely, to enable the developer to set any of the effects via Client-Side JavaScript. Why not just type dojo.coords(_id).t directly into the top property? First, because _id has a specific meaning to the XSP Command Manager, so it throws an error. Second, because the top property must be a number, not a string. So you must use the attributes property to pass the function, which sets top to the node’s current top property, to the browser. This function also shows how to retrieve a node’s current position to slide a node relative to that current position.
Listing 5.19. Slide Effect with attributes Property
<xp:button
value="Slide left"
id="button8">
<xp:eventHandler
event="onclick"
submit="false">
<xp:this.script>
<xe:dojofxSlideTo
node="effect1"
left="0">
<xp:this.attributes>
<xp:parameter
name="top"
value="dojo.coords(_id).t">
</xp:parameter>
</xp:this.attributes>
</xe:dojofxSlideTo>
</xp:this.script>
</xp:eventHandler>
</xp:button>
Table 5.15 shows the significant properties of the Dojo Slide To Effect.
Table 5.15. xe:dojofxSlideTo Properties
|
Property |
Description |
|
left |
Defines how far relative to the left of the screen the node should be slid. |
|
top |
Defines how far relative to the top of the screen the node should be slid. |
Dojo Animation
The Dojo animation effect implements the dojo.animateProperty object within a simple action. The effect has all the properties already covered in the other Dojo effect simple actions. In addition, there are some specific properties. You can use the delay property to add a delay in milliseconds before the effect should start. You can use the rate property to change the number of frames per second at which the animation runs; by default, it is 100 frames per second, which is rather quick. The value of the rate property is a number in milliseconds, so to change it to 5 frames per second, the value would be 200 (200 × 5 = 1000 milliseconds = 1 second). You can use the repeat property to repeat the animation a certain number of times. But the most important property is the properties property, allowing one or more xe:dojoAnimationProps objects to be added. These handle what animation runs and its varying settings.
Table 5.16 shows the main properties for the Dojo animation effect.
Table 5.16. xe:dojoDojoAnimateProperty Properties
|
Property |
Description |
|
delay |
Defines the delay before the animation begins. |
|
duration |
Defines the duration of the animation. |
|
easing |
Requires a Client-Side JavaScript function to define the rate of acceleration of the animation. |
|
node |
Defines the node to which the animation should be applied. |
|
properties |
Defines the animation properties. |
|
rate |
Defines the rate per second, taking a value in milliseconds. |
|
repeat |
Defines the number of times the animation should repeat. |
|
var |
Defines a variable name under which the animation runs. |
In addition to the loaded property, the xe:dojoAnimationProps object has four properties shown in Table 5.17. The Extension Library demo database has an example of this on the Core_DojoEffects.xsp XPage, for increasing the size of a box, shown in Listing 5.20. Line 9 sets the animation to run on the bluebox component. Lines 14 and 15 define the starting and ending width and height of the box.
Table 5.17. xe:dojoDojoAnimationProps Properties
|
Property |
Description |
|
end |
Defines the ending value of the attribute this animation applies to. |
|
name |
Defines the attribute this animation applies to, such as “width” or “height”. |
|
start |
Defines the starting value for the attribute this animation applies to. |
|
unit |
Defines the unit for the values in start and end. |
Listing 5.20. Core_DojoEffect.xsp Dojo Animation Simple Action
1 <xp:button 2 value="Grow the box" 3 id="button5"> 4 <xp:eventHandler 5 event="onclick" 6 submit="false"> 7 <xp:this.script> 8 <xe:dojoAnimateProperty 9 node="bluebox" 10 duration="3000"> 11 <xp:this.properties> 12 <xe:dojoAnimationProps 13 name="width" 14 start="200" 15 end="400"> 16 </xe:dojoAnimationProps> 17 <xe:dojoAnimationProps 18 name="height" 19 start="200" 20 end="400"> 21 </xe:dojoAnimationProps> 22 </xp:this.properties> 23 </xe:dojoAnimateProperty> 24 </xp:this.script> 25 </xp:eventHandler> 26 </xp:button>
Earlier in this chapter, code was provided to style the ToggleButton control. At this point, it is appropriate to revisit that code, shown in Listing 5.13. Listing 5.21 shows alternate code for the ToggleButton using a Dojo animation simple action, with the output shown in Figure 5.20. To revisit the functionality, the animation should change the font color of the ToggleButton, alternating between red and green. However, the properties of the xe:dojoAnimationProps object can only accept literal values or Server-Side JavaScript returning a literal value. It is not possible to add Client-Side JavaScript code to ensure the end color alternates. As a result, you must use the attributes property to compute the properties object in Client-Side JavaScript, in lines 16 to 29. Line 18 creates the color object (the name property of an xe:dojoAnimationProps object). Line 19 sets the start attribute of the color object, although _id.style.color is not set when the page is loaded. Lines 20 to 26 set the end attribute to a function that sets the color to red if it is initially green, otherwise red.
)
Figure 5.20. Dojo Fade In Effect.
Listing 5.21. Using Dojo Animation Simple Action to Style the ToggleButton
1 <xe:djToggleButton
2 id="djToggleButton2"
3 value="#{sessionScope.djButton3}"
4 label="Toggle Button"
5 checkedValue="Checked..."
6 uncheckedValue="Not Checked..."
7 style="color:rgb(255,0,0)">
8 <xp:eventHandler
9 event="onclick"
10 submit="false">
11 <xp:this.script>
12 <xe:dojoAnimateProperty
13 node="djToggleButton2"
14 duration="500">
15 <xe:this.attributes>
16 <xp:parameter
17 name="properties">
18 <xp:this.value><![CDATA[{"color":
19 {"start":_id.style.color,
20 "end":function() {
21 if (_id.style.color=="rgb(0, 255, 0)") {
22 return "rgb(255,0,0)";
23 } else {
24 return "rgb(0,255,0)";
25 }
26 }
27}
28}]]></xp:this.value>
29 </xp:parameter>
30 </xe:this.attributes>
31 </xe:dojoAnimateProperty>
32 </xp:this.script>
33 </xp:eventHandler>
34 </xe:djToggleButton>