Defining a Timer's Action
In the preceding section, we defined the syntax for the <timer> tag that sets the length of the timer. When you define the action that a timer will initiate, there are two different syntactical expressions that you may use.
In the preceding examples in this chapter, we have used the ontimer attribute in the <card> tag to establish an action the timer will execute. Although this is the simplest way to code a timer element, what we've really shown is a shorthand version of the <onevent> tag discussed in Chapter 4. The action initiated by a timer is an intrinsic event, and as such can be coded with the <onevent> tag.
▸ For more about intrinsic events in general, and the <onevent> tag in particular, see Chapter 4's section on events.
Why are there two ways to establish what action the timer will execute? Which one is better to use? The following section explains the differences between these two options and shows you how and when to use them.
A Basic Timer Action with the <card> Tag
As we've already seen in this chapter, you can attach an action to your timer using the ontimer attribute in the <card> tag. When you use this option, the ontimer attribute basically functions as a <go> task within the timer element, directing a navigational action.
Let's look at a snippet of code from Listing 10.1 to see this in action:
<card id="splash" title="Welcome" ontimer="#main">
<timer value="40"/>
<p>
You're about to enter a tasty WAP site!
</p>
</card>
In this example, the ontimer attribute simply sends the user to another card in the deck when the timer expires.
Note
You can use any navigational format (relative links, absolute links, or link fragments) with the ontimer attribute. For more information on navigational formats, see Chapter 4.
Using the ontimer attribute in the <card> tag is a quick way to code a navigational action for your timer, but its action is limited to navigational tasks. For other kinds of tasks, you will need to use the expanded <onevent> tag.
Expanded Timer Actions with the <onevent> Tag
As you may remember from Chapter 4, the <onevent> tag has four possible type attributes: oneventforward, oneventbackward, onpick, and ontimer. These types are essentially triggers for some kind of action, or task, and there are four kinds of tasks that each of these triggers can initiate. Those four tasks include: <go>, <prev>, <refresh>, and <noop>.
Tip
Use the <onevent> tag for your timers only when you need the extended functionality of a <prev> or <refresh> task in your timer. Other times, use the ontimer attribute in the <card> tag.
With the <onevent> tag, you can create timers that not only navigate the user to a new location but take him back to the previous page or refresh the content on the device. When you do find uses for this kind of functionality in your timer, you'll need to code the timer differently. Let's examine what an <onevent> timer looks like compared to a <card> timer.
The first card from Listing 10.1 used the <card> tag shorthand and looked like this:
<card id="splash" title="Welcome" ontimer="#main">
<timer value="40"/>
<p>
You're about to enter a tasty WAP site!
</p>
</card>
That card is equivalent to the following <onevent> longhand code:
<card id="splash" title="Welcome">
<onevent type="ontimer">
<go href="#main"/>
</onevent>
<timer value="40"/>
<p>
You're about to enter a tasty WAP site!
</p>
</card>
As you can see, the <onevent> timer coding is more complex and will take longer to code. With that in mind, let's look at an example that shows the advanced functionality we can gain by using this more complex syntax.
Now, let's create a new deck for the BurgerWorld WAP site that will give users a way to find out more detailed help information about the WAP site on the Web. Why would something like this be a good candidate for a timer? If a user has already chosen to reference the help deck, he might be unsure how to navigate back to the location he came from. By setting a 60-second timer for this card, any potentially confused users will be automatically returned to the most recent location they visited.
In Listing 10.2, you can see how the <onevent> tag can be used to create a timer that returns the user to his previous location in the history stack.
Listing 10.2 A Deck That Returns the User to the Previous Location After 40 Seconds
You can see what the help card looks like in Figure 10.3.
Note
The example in Listing 10.2 assumes that the user has previous pages stored in the browser's history stack. If there is no previous page in the browser cache, this example will generate an error.
Figure 10.3. This help screen shows a short message, then returns the user to the last place in their history stack after 10 seconds.
Listing 10.2 uses the <onevent> tag, with its type attribute set to ontimer. Nested inside the <onevent> tag is the <prev> task, which sends the user to the previous location in the history stack when the timer event has executed. In this case, the <timer> tag was set to a value of 100, or 10 seconds.
Listing 10.3 provides a more complex example of the <onevent> tag, one where we use a timer to refresh a session variable. This code refreshes credit card information if the user stays on any single card in the deck for more than 5 minutes. It's intended to reset the card information to null if the user walks away from the device for more than 5 minutes.
Listing 10.3 A Timer That Refreshes Session Variables
Note
In some browsers, the "buy" soft key will only appear once the user has entered in the variable data.
Listing 10.3 is the most advanced example of a timer that we've yet encountered in this chapter. The application accepts credit card information from the user. If the user doesn't confirm her order within 5 minutes, the stored credit card number and expiration date are reset to zero.
The first card is strictly informational: it tells the user about a product and asks her whether she wants to proceed and buy it. A soft-key has been set up to navigate the user to the next card if she wants to proceed, as you can see in Figure 10.4.
Figure 10.4. The application shows the user the price of the super-rocket and offers a soft key to buy it.
The second card (see Figure 10.5) asks the user to enter a credit card number and expiration date and is where the user establishes variables that our timer will clear, if needed. Again, a soft key has been set up to navigate the user to the next card.
Figure 10.5. The UP.Simulator only shows one input element per card. Here we see the application request a credit card number from the user.
The third card (see Figure 10.6) contains the timer itself. It verifies that credit card number for the user and allows her to confirm her purchase. If that confirmation does not happen within five minutes, the session variables named ccn and date (which represent a credit card number and expiration date) will be reset to zero.
Figure 10.6. This card shows the completed order confirmation.
This example, while complex, demonstrates some of the advanced actions that can be linked to a timer using the <onevent> tag.
Figure 10.7. This card shows the expired confirmation card, where the variables are reset to zero.
