Using the Page Alert Component

February 2006 [Revision number: V2-1]

Copyright 2006 Sun Microsystems, Inc.

In this tutorial, you use the Sun Java Studio Creator integrated development environment (IDE) to create Page Alerts of type error, information, warning, and question. Each Page Alert contains Back, Next, and Cancel buttons when appropriate. Contents - What Is a Page Alert - Designing the Start Page - Adding Properties to the SessionBean - Configuring the Start Page Buttons - Creating a Page to Display the Page Alerts - Adding a Group Panel to the Page Alert - Creating the Alert Status Page - Defining Page Navigation - Running and Testing the Application

What Is a Page Alert

The Page Alert component is similar to the Alert component, but it is intended for displaying dynamic messages on a separate page. The Page Alert offers the choice of error, warning, information, and success icons. You use the title, summary, and detail properties to set the component's text, and the type property to specify which icon to display. From a practical standpoint, the Page Alert component is not very useful unless you add a button to the component that enables the user to navigate through your application. Because of this, the Page Alert component comes with a pageAlertButton Facet. The Sun Java Studio Creator IDE does not have direct support for Facets. Nor does the IDE enable the user to paste JSP source directly. In the case of Page Alerts, this means that you cannot simply drag and drop buttons onto a Page Alert and expect the component to render properly at runtime. Nor can you type the required source directly into the JSP source and expect the designer to render properly. To nest components such as buttons within the Page Alert component, you add a Group Panel to the Page Alert and then ensure that the groupPanel is included in the f:facet tag. Once this is done, you can add buttons to the Group Panel.

Designing the Start Page

This tutorial takes you through creating each of the four Page Alert types and demonstrates the creation of the pageAlertButton Facet. The project you create in this tutorial has three pages. The first page defines which Page Alert is rendered. The second page defines the chosen Page Alert and the pageAlertButton facet. The final page is a status page showing the outcome of the user's action on the Page Alert. In this section, you create the first page, as shown in the following figure.

Figure 1: Four Page Alerts

1. Create a new web application and name it PageAlertExample. 2. From the Basic section of the Components Palette, drag a Label component and drop it at the top of the page. In the Properties window, set the text property to Page Alert Button Facets and the labelLevel property to Strong(1). 3. From the Basic section of the Palette, drag a Button component onto the page. Set the text property of the Button to Question and set its id property to questionBtn. 4. Drag a Label onto the page and place it to the right of the Question button. Set its text to Render a Question Page Alert. 5. Drag three more Buttons and corresponding Labels onto the Visual Designer and configure them as follows: a. Set the text property of the second Button to Error and its id property to errorBtn. Set its Label's text property to Render an Error Page Alert. b. Set the text property of the third Button to Warning and its id property to warningBtn. Set its Label's text property to Render a Warning Page Alert. c. Set the text property of the fourth Button to Information and its id property to infoBtn. Set its Label's text property to Render an Information Page Alert. 6. From the Basic section of the Palette, drag a Message Group component onto the page and place it beneath the Buttons.

Adding Properties to the SessionBean

In this section, you initialize three SessionBean variables. The first SessionBean variable holds information about the page alert. The second variable holds a String message for the user after viewing the Page Alert. The third SessionBean variable determines if the Next button should be visible on the browser page. 1. In the Projects window, right-click SessionBean > SessionBean1 and choose Add > Property. 2. In the New Property Pattern dialog box, set the Name to userPageAlert, set the Type to com.sun.rave.web.ui. component.PageAlert, and then click OK.

3. Repeat Step 1 to create another property. In the New Property Pattern dialog box, set the Name to userMessage, set the Type to String, and then click OK. 4. Create a third property. In the New Property Pattern dialog box, set the Name to userVisible, set the Type to boolean, and then click OK. NOTE: The Type is case sensitive. Make sure you choose boolean and not Boolean.

Configuring the Start Page Buttons

Here, you add behaviors to the buttons on the Start page. 1. In the Visual Designer, double-click the Question button to see the button's action() method. Add the following code marked in bold: Code Sample 1: Define the Question Page Alert public String questionBtn_action() { PageAlert questionAlert = new PageAlert(); questionAlert.setType("question"); questionAlert.setDetail("Please press Next to begin machine upgrade."); questionAlert.setSummary("Information Lab Maintenance - Machine Upgrade"); questionAlert.setTitle(" " + "Machine Upgrade - Install"); getSessionBean1().setUserPageAlert(questionAlert); getSessionBean1().setUserVisible(true); return null; }

2. Fix the import statements by pressing Alt-Shift-F. You can reformat the code in this and other code fragments you add to the project by pressing CTRL-Shift-F. 3. Press the Design button to return to the Visual Designer. 4. Double-click the Error button and add the following event handler code to the errorBtn_action() method: Code Sample 2: Define the Error Page Alert public String errorBtn_action() { PageAlert errorAlert = new PageAlert(); errorAlert.setType("error"); errorAlert.setDetail("Installation failed: Insufficient Privileges!"); errorAlert.setSummary("An Error has Occurred!"); errorAlert.setTitle(" " + "Machine Upgrade - Error"); getSessionBean1().setUserPageAlert(errorAlert); getSessionBean1().setUserVisible(false); return null; }

5. Return to the Visual Designer and double-click the Warning button. Add the following source to the warningBtn_action() method:

Code Sample 3: Define the Warning Page Alert public String warningBtn_action() { PageAlert warningAlert = new PageAlert(); warningAlert.setType("warning"); warningAlert.setDetail("Warning: Patch 12345-01 is missing." + " Press Next to install patch prior to upgrade"); warningAlert.setSummary("Missing Patch is required"); warningAlert.setTitle(" " + "Machine Upgrade - Warning"); getSessionBean1().setUserPageAlert(warningAlert); getSessionBean1().setUserVisible(true); return null; }

6. Return to the Visual Designer, double-click the Information button, and add the following source to the infoBtn_action() method: Code Sample 4: Define the Information Page Alert public String infoBtn_action() { PageAlert informationAlert = new PageAlert(); informationAlert.setType("information"); informationAlert.setDetail("Installation has completed successfully."); informationAlert.setSummary("Install complete"); informationAlert.setTitle(" " + "Machine Upgrade - Completed"); getSessionBean1().setUserPageAlert(informationAlert); getSessionBean1().setUserVisible(true); return null; }

7. Press CTRL-Shift-S to save the code, and then return to the Visual Designer.

Creating a Page to Display the Page Alerts

Now, create a page that displays the Page Alerts. You bind properties of the Page Alerts to the Session Bean's userPageAlert to allow for reusability. The figure below shows the page that you will create in this and the following sections.

Figure 2: Completed Start Page

1. In the Projects window, right-click the Web Pages node, and choose New > Page. Name the new page UserAlert and click Finish. 2. From the Layout section of the Palette, drag a Page Alert component onto the UserAlert page. 3. Right-click the Page Alert component and choose Property Bindings from the pop-up menu. 4. In the Selecting binding target column, expand SessionBean1 > userPageAlert. 5. Bind the following properties to the following targets. You set a binding target by selecting it as shown in the figure below. a. b. c. d. Bind the type property to #{SessionBean1.userPageAlert.type}. Click Apply. Bind the detail property to #{SessionBean1.userPageAlert.detail}. Click Apply Bind the summary property to #{SessionBean1.userPageAlert.summary}. Click Apply Bind the title property to #{SessionBean1.userPageAlert.title}. Click Apply

When you click Apply, the property is bound and turns bold to indicate that it has a value. In addition, the New binding expression field shows the binding target.

Figure 3: Property Bindings for pageAlert1 6. Click the Close button.

Adding a Group Panel to the Page Alert

Here you create the pageAlertButton facet, and add a Group Panel component and a series of Button components that allow for navigation to and from the page. 1. From the Layout section of the Palette, drag a Group Panel onto the Page Alert component. The Page Alert briefly shows a blue highlight to indicate that Group Panel is a valid child. 2. Click the JSP button and manually add the following tags, marked in bold, around the groupPanel's ui:panelGroup tag, and save the changes.

Code Sample 5: Manually Create pageAlertButtons Facet <ui:pageAlert binding="#{UserAlert.pageAlert1}" detail="#{SessionBean1.myPageAlert.detail}" id="pageAlert1" style="left: 24px; top: 24px; position: absolute" summary="#{SessionBean1.myPageAlert.summary}" title="#{SessionBean1.myPageAlert.title}" type="#{SessionBean1.myPageAlert.type}"> <f:facet name="pageAlertButtons"> <ui:panelGroup binding="#{UserAlert.groupPanel1}" id="groupPanel1"/> </f:facet> </ui:pageAlert>

3. Return to the Visual Designer. Note that the Group Panel is right justified in the Page Alert. This alignment is defined by the pageAlertButtons facet. 4. From the Basic section of the Palette, drag a Button onto the Group Panel. Before you drop the button, make sure that only the Group Panel is highlighted in blue. In the Properties window, change its text property to Back, and change the button's id to backBtn. 5. Drag a second Button onto the Group Panel. This time, make sure that only the Back button is highlighted in blue before dropping the button. Change the Button's text property to Next, and change the button's id to nextBtn. Under the Behavior section of the Properties window click the ellipsis button (...) for the visible property. 6. In the Property dialog box, select the Use binding option. On the Bind to an Object tab, select SessionBean1 > userVisible as shown in Figure 4, and click OK.

Figure 4 : Object Binding Note: The Next button disappears from the Visual Designer after you bind it, because the default value is False. This is the expected behavior. To select this button, choose it in the Outline window. 7. Drag a third Button onto the Group Panel, and again make sure that only the Back button is highlighted in blue before dropping the button.. Change its text property to Cancel. Change the button's id to cancelBtn, and select the checkbox associated with the primary property. This sets it value to True. Selecting the primary property makes the Cancel button the default button which is activated when the page is rendered.

8. Go back to the JSP view. Inside the <f:facet> tags, you can see the code in which you have defined the action of the Back, Next, and Cancel navigation buttons: Code Sample 6: View of Completed pageAlertButtons Facet ... <ui:pageAlert binding="#{UserAlert.pageAlert1}" detail="#{SessionBean1.myPageAlert.detail}" id="pageAlert1" style="left: 24px; top: 24px; position: absolute" summary="#{SessionBean1.myPageAlert.summary}" title="#{SessionBean1.myPageAlert.title}" type="#{SessionBean1.userPageAlert.type}"> <f:facet name="pageAlertButtons"> <ui:panelGroup binding="#{UserAlert.groupPanel1}" id="groupPanel1"> <ui:button action="back" binding="#{UserAlert.backBtn}" id="backBtn" text="Back"/> <ui:button action="#{UserAlert.nextBtn_action}" binding="#{UserAlert.nextBtn}" id="nextBtn" text="Next" visible="#{SessionBean1.userVisible}"/> <ui:button action="cancel" binding="#{UserAlert.cancelBtn}" id="cancelBtn" primary="true" text="Cancel"/> </ui:panelGroup> </f:facet> </ui:pageAlert> ...

9. Go back to the Visual Designer, and double-click the Cancel button. Add the following source to the button's cancelBtn_action() method: Code Sample 7: Add Cancel Button Source public String cancelBtn_action() { info("Installation has been cancelled by the user."); return null; }

When the Cancel button is clicked, an informational FacesMessage picked up by the Message Group component on Page1 is generated. 10. Go back to the Visual Designer. In the Outline window, right-click the nextBtn node and select Edit action Event Handler. This opens the Java editor to the Next button's nextBtn_action() method. Add the following source. Note that you replace the line return null; with return "next";.

Code Sample 8: Add Next Button Source public String nextBtn_action() { PageAlert pa = getSessionBean1().getUserPageAlert(); String type = pa.getType(); /*Note that type error should never occur since the *next button does not render when type is set to error.*/ if (type != null) { if (type == "question") { getSessionBean1().setUserMessage ("Your machine has been successfully upgraded."); } if (type == "error") { getSessionBean1().setUserMessage ("Please correct the permissions and restart."); } if (type == "warning") { getSessionBean1().setUserMessage("Patch installed successfully. " + "Installation has completed."); } if (type == "information") { getSessionBean1().setUserMessage("Please fill out our survey!"); } } else { getSessionBean1().setUserMessage("Application Error!"); } return "next"; }

When the user clicks the Next button, the userMessage is set with a value appropriate for the type of alert being used in the browser's session. 11. Reformat the code, press Ctrl-S to save the changes, and return to the Visual Designer.

Creating the Alert Status Page

In this section, you create the status page resulting from proceeding through the Page Alert. You also add a button to enable the user to access the Start page of the application easily. The figure below shows the page that you will create in the following steps.

Figure 5: Completed Alert Status Page

1. Create a new web page and name it AlertStatus. 2. Drag a Label onto the page. 3. Right-click the Label and choose Property Bindings from the pop-up menu.

4. Under Select bindable property, choose text. In the Select binding target column, select SessionBean1 > userMessage. Click Apply to set the value and then click Close. The Label's text displays abc in the Visual Designer to show it is bound. 5. Select the Label. In the Properties window, open the style property by clicking its ellipsis (...) button. Set the font size to 18 and click OK. 6. Drag a Button onto the page. Set its id to returnBtn and its text to Return to Start Page.

Defining Page Navigation

Now, you tie all three of the pages together using the Page Navigation Editor. 1. Right-click in the Visual Designer, choose Page Navigation from the pop-up menu, and then select Page1.jsp. a. b. c. d. Link Page1.questionBtn to the UserAlert Page and name the link question. Link Page1.errorBtn to the UserAlert Page and name the link error. Link Page1.warningBtn to the UserAlert Page and name the link warning. Link Page1.infoBtn to the UserAlert Page and name the link information.

2. Select UserAlert.jsp. a. Link UserAlert.backBtn to Page1 and name the link back. b. Link UserAlert.nextBtn to the AlertStatus Page and name the link next. c. Link UserAlert.cancelBtn to Page1 and name the link cancel. 3. Select AlertStatus.jsp and link AlertStatus.returnBtn to Page1. Name the link start. The result of these links looks like the figure below.

Figure 6: Completed Page Navigation

Running and Testing the Application

To test the application, perform the following steps. 1. Deploy and run the application by clicking the Run Main Project button. Page 1 renders, as shown in Figure 7 below.

10

Figure 7: Deployed Page Alert Application 2. Explore the application by clicking the buttons. Each button renders a different Page Alert icon and message. Clicking the Back or Cancel buttons returns you to Page 1. The Message Group component shows the Installation cancelled message displayed in the figure below.

Figure 8: Cancel Button Message 3. Click the Next button on the Question, Warning, or Information Alert page. This brings you to the Status page. Each Status message is unique to the Alert. The Error Page Alert does not have a Next button, as you can see in Figure 9 below.

11

Figure 9: Error Page Without Next Button

See Also:
q q q

Delving Into Components Using Message Components Understanding Scope and Managed Beans

More Developer Resources: For more tutorials, articles, tips, and expert advice for developers, visit the Java Studio Creator developer resources on the Sun Developer Network (SDN)

This page was last modified: February 10, 2006

Sun and Third-party Trademarked Terminology

The following Sun trademarked terms might be used in the Sun Java(tm) Studio Creator tutorials:
q q q q q q q q q

Sun Java Studio Creator integrated development environment (IDE) Sun Java System Application Server version number (Application Server) Java Platform, Standard Edition technology (Java SE(tm) platform) JavaServer(tm) Faces technology JavaServer Pages(tm) technology (JSP(tm) technology) Sun Java System Web Server version number (Web Server) Java Database Connectivity software (JDBC software) Enterprise JavaBeans(tm) specification (EJB(tm) specification) Solaris(tm) Operating System software (Solaris OS software)

The following third-party trademarked terms might be used in the Sun Java Studio Creator tutorials:
q q

UNIX(R) software SPARC(R) processor

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software.

12

Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. Sun, Sun Microsystems, the Sun logo, Java and the Java Coffee Cup logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited. Note: Sun is not responsible for the availability of third-party web sites mentioned in this document and does not endorse and is not responsible or liable for any content, advertising, products, or other materials on or available from such sites or resources. Sun will not be responsible or liable for any damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services available on or through any such sites or resources.

Copyright 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, tats-Unis. Tous droits rservs. Sun Microsystems, Inc. dtient les droits de proprit intellectuels relatifs la technologie incorpore dans le produit qui est dcrit dans ce document. En particulier, et ce sans limitation, ces droits de proprit intellectuelle peuvent inclure un ou plus des brevets amricains lists l'adresse http://www.sun.com/patents et un ou les brevets supplmentaires ou les applications de brevet en attente aux tats-Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence. Sun, Sun Microsystems, le logo Sun, Java et le logo Java Coffee Cup sont des marques de fabrique ou des marques dposes de Sun Microsystems, Inc. aux tats-Unis et dans d'autres pays.Ce produit est soumis la lgislation amricaine en matire de contrle des exportations et peut tre soumis la rglementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nuclaires,des missiles, des armes biologiques et chimiques ou du nuclaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou rexportations vers les pays sous embargo amricain, ou vers des entits figurant sur les listes d'exclusion d'exportation amricaines, y compris, mais de manire non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une faon directe ou indirecte, aux exportations des produits ou des services qui sont rgis par la lgislation amricaine en matire de contrle des exportations et la liste de ressortissants spcifiquement dsigns, sont rigoureusement interdites. Sun Microsystems n'est pas responsable de la disponibilit de tiers emplacements d'enchanement mentionns dans ce document et n'approuve pas et n'est pas responsable ou iresponsable d'aucun contenu, de la publicit, de produits, ou d'autres matriaux dessus ou fournis par de tels emplacements ou ressources. Sun ne sera pas responsable ou iresponsable d'aucuns dommages ou perte causs ou allgus pour tre caus par ou en liaison avec l'utilisation de ce produit ou la confiance dans des tels contenu, marchandises, ou services disponibles sur ou par des tels emplacements ou ressources.

13