Indicating Action Status
You’ve learned how to invoke actions asynchronously. To notify users when asynchronous actions are being performed, use the actionStatus component in conjunction with any action component.
The actionStatus component can notify users of two states: when an asynchronous action is started and when it is stopped. To use it, place it in the location on your page where you want to show the status message. Use the startText and stopText attributes to specify the messages to be shown to the user. If you need to pass arguments to the action, use a nested param component.
Listing 7.7 provides an example of using the actionStatus component, building on the page from Listing 7.6 and the controller from Listing 7.4. When the text field receives focus, the action is fired, and the status message changes to Started. When the action is complete, the status message is set to Stopped.
Listing 7.7 Visualforce Page Using actionStatus
<apex:page controller="MyPageController7_3">
<apex:outputPanel id="result">
<apex:pageMessages />
</apex:outputPanel>
<apex:actionStatus id="status"
startText="Started" stopText="Stopped" />
<apex:form>
<apex:inputText>
<apex:actionSupport action="{!timesTwo}"
event="onfocus" reRender="result" status="status" />
</apex:inputText>
</apex:form>
</apex:page>
To display an image or a stylized message, you can use the start and stop facets. Facets are modifiers accepted by some Visualforce components to specify rich values that cannot be contained in XML attributes, such as nested HTML elements. Listing 7.8 is an example of using the facets to mark up the status message with H2 HTML heading elements.
Listing 7.8 Code Snippet Using actionStatus with Facets
<apex:actionStatus id="status">
<apex:facet name="stop">
<h2>Stopped</h2>
</apex:facet>
<apex:facet name="start">
<h2>Started</h2>
</apex:facet>
</apex:actionStatus>
To display a dynamic status message, you can write a JavaScript function to modify HTML elements on the page and call it from the actionStatus component. The actionStatus component supports the onStart and onStop attributes, which specify JavaScript functions to be invoked when the associated action is started and stopped. Listing 7.9 provides an example of this usage, using JavaScript to update the HTML content of an outputPanel in response to the actionStatus changing state.
Listing 7.9 Code Snippet Using actionStatus with JavaScript
<apex:page controller="MyPageController7_3">
<script type="text/javascript">
function start() {
document.getElementById("{!$Component.myStatus}").innerHTML = 'Started';
}
function stop() {
document.getElementById("{!$Component.myStatus}").innerHTML = 'Stopped';
}
</script>
<apex:outputPanel id="result">
<apex:pageMessages />
</apex:outputPanel>
<apex:actionStatus id="status"
onStart="start();" onStop="stop();" />
<apex:outputPanel id="myStatus"></apex:outputPanel>
<apex:form>
<apex:inputText>
<apex:actionSupport action="{!timesTwo}"
event="onfocus" reRender="result" status="status" />
</apex:inputText>
</apex:form>
</apex:page>
Referencing Visualforce Components from JavaScript
In Listing 7.9, the status of the action invocation is displayed in the element myStatus using JavaScript. For the purposes of the example, the element is an outputPanel Visualforce component rather than a simple div tag. This illustrates an important aspect of using JavaScript in Visualforce pages.
Each Visualforce component is assigned a unique identifier, set in its id attribute. When you override this id attribute and provide your own value, Visualforce fully qualifies it by affixing the identifiers of any containers included between your component and the root page component.
If your JavaScript code attempts to reference a Visualforce component using the raw identifier as it appears in the HTML, it will fail to locate it. Instead, use {!$Component.id}, where id is the identifier you set on your Visualforce component. When the page is rendered, Visualforce reads this token and replaces it with the fully qualified value of the identifier. If the identifier cannot be found, the token is replaced with an empty string.
If your component is contained within a form component, you must provide the form with an id value as well and include the form identifier in the component reference. For example, if the form identifier is myForm and the component you want to obtain a reference to is myText, the usage is {!$Component.myForm:myText}.
Tip
Use the View Source feature of your Web browser or a plug-in such as Firebug to debug component identifier problems.