The standard Visualforce <apex:actionPoller/> component sends AJAX requests to the server based on the specified time interval. An example use case is a countdown timer that sends the user to another page when the timer expires. But what if the action poller should stop when a condition in the controller becomes true, for example, when a batch apex job completes or an update is received from a third-party system?
In this recipe, we will simulate the progression of a payment through a number of states. An action poller will be used to retrieve the latest state from the server and display it to the user. Once the payment reaches the state Complete, the action poller will be disabled.
This recipe makes use of a custom controller, so this will need to be created before the Visualforce page.
Navigate to the Apex Classes setup page by clicking on Your Name | Setup | Develop | Apex Classes.
Click on the New button.
Paste the contents of the
PollerController.clsApex class from the code download into the Apex Class area.Click on the Save button.
Next, create the Visualforce page by navigating to the Visualforce setup page, clicking on Your Name | Setup | Develop | Visualforce Pages.
Click on the New button.
Enter
ActionPollerin the Label field.Accept the default ActionPoller that is automatically generated for the Name field.
Paste the contents of the
ActionPoller.pagefile from the code download into the Visualforce Markup area.Click on the Save button to save the page.
Navigate to the Visualforce setup page by clicking on Your Name | Setup | Develop | Visualforce Pages.
Locate the entry for the ActionPoller page and click on the Security link.
On the resulting page, select which profiles should have access and click on the Save button.
Opening the following URL in your browser displays the ActionPoller page: https://<instance>/apex/ActionPoller.
Here, <instance> is the Salesforce instance specific to your organization, for example, na6.salesforce.com.
The page polls the server for the current state, displaying the message Polling ... when the action poller executes, as shown in the following screenshot:
Once the current state reaches Complete, the action poller terminates.
The key to this recipe is the enabled attribute on the actionPoller component:
<apex:actionPoller action="{!movePayment}"
rerender="payment" interval="5" status="status"
enabled="{!paymentState!='Complete'}"/>
This merge field references the paymentState property from the custom controller, which is evaluated each time the action poller executes until it becomes false. At that point, the action poller is permanently disabled.
The Polling ... message is generated by the actionStatus component associated with the action poller. This component has a startText attribute but not a stopText attribute, which means that the text will only be displayed while the AJAX request is in progress:
<apex:actionStatus startText="Polling ..." id="status"/>
The Using action functions recipe in Chapter 7, Enhancing the Client with JavaScript shows how to execute a controller action method from JavaScript.