Author: michael.yuan(a)jboss.com Date: 2007-08-10 01:35:34 -0400 (Fri, 10 Aug 2007) New Revision: 3034 Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamJsfEditor.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj01.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj02.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj03.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj04.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj05.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj06.png trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj07.png Modified: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml Log: Initial version of the Seam chapter Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamJsfEditor.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamJsfEditor.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj01.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj01.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj02.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj02.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj03.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj03.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj04.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj04.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj05.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj05.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj06.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj06.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Added: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj07.png =================================================================== (Binary files differ) Property changes on: trunk/documentation/GettingStartedGuide/docs/userguide/en/images/SeamNewProj07.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml =================================================================== --- trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml 2007-08-10 05:31:10 UTC (rev 3033) +++ trunk/documentation/GettingStartedGuide/docs/userguide/en/modules/GetStartSeamGen.xml 2007-08-10 05:35:34 UTC (rev 3034) @@ -1,688 +1,371 @@ <?xml version="1.0" encoding="UTF-8"?> <chapter id="GetStartSeamGen" xreflabel="GetStartSeamGen"> - <?dbhtml filename="GetStartSeamGen.html"?> - <chapterinfo> - <keywordset> - <keyword>Red Hat Developer Studio</keyword> - <keyword>Seam</keyword> - <keyword>JBoss</keyword> - <keyword>CRUD-application</keyword> - </keywordset> - </chapterinfo> - - <title>Getting Started with Seam Gen</title> -<para>In this chapter we will see how easy it is to build Seam applications and integrate -them with Ajax4jsf and Rich Faces. We will bootstrap the application using Seam Gen which is - a CRUD application generator. Seam Gen can be used from either the command line or via an - Red Hat Developer Studio. Unlike most application generators, Seam Gen can also be used to - incrementally add more functionality to an existing Seam application.</para> - <para>Seam is an incredibly flexible development framework that can be completely - integrated with a Java EE server or in a simple POJO environment like Tomcat. Seam is - also extremely portable, and has been tested on several popular containers like JBoss, - Tomcat, Weblogic, WebSphere. Seam uses JSF as its view layer and can use either JSP or - Facelets as the presentation layer.</para> - <para>Seam Gen generates all the required layers of an application. It uses JPA as the - persistence layer, POJO&apos;s (Plain Old Java Objects) as the business logic layer and - Facelets as the presentation layer.</para> - <para>We will perform the following steps in this chapter of the tutorial:</para> - <itemizedlist> - <listitem>Creating a Seam Project using Seam Gen</listitem> - <listitem>Generating a Seam application using Seam Gen</listitem> - <listitem>Running the Seam application</listitem> - <listitem>Customizing the generated Seam application</listitem> - <listitem>Adding AJAX features to automatically generated JSF Seam UI components</listitem> - <listitem>Replacing standard JSF UI components with AJAX enabled rich UI components - provided by the Red Hat Developer Studio</listitem> - <listitem>Using AJAX components to do live validation on web pages</listitem> - <listitem>Adding Rich Faces components to a Seam application</listitem> - </itemizedlist> -<section id="CreatingASeamProjectUsingSeamGen"> -<?dbhtml filename="CreatingASeamProjectUsingSeamGen.html"?> -<title>Creating a Seam Project using Seam Gen</title> -<itemizedlist> -<listitem>Stop your JBoss AS Server by clicking on the stop button as shown below. We are - doing this so that the generated application can be deployed properly when the server - starts.</listitem> - </itemizedlist> - <figure> -<title>Stopping JBoss AS Server</title> -<mediaobject> + <?dbhtml filename="GetStartSeamGen.html"?> + <chapterinfo> + <keywordset> + <keyword>Red Hat Developer Studio</keyword> + <keyword>Seam</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Write Your First Web Application</title> + + <para>The Red Hat Developer Studio provides sophisticated tools for enterprise applications. With the Red Hat Developer Studio, you can get started very quickly with a web prototype, and then scale up your application to include enterprise features (e.g., business processes, web services, etc.) using the same developer tools. It is a "scalable" RAD (Rapid Application Development) tool.</para> + + <para>A core element that makes the Red Hat Developer Studio "scalable" is the JBoss Seam framework. Seam is a fully featured application framework on top of Java EE 5. It is also one of the most popular enterprise Java framework today. Seam deeply integrates many other standard-based or open source frameworks (e.g., JSF, EJB3, JMS, Web Services, jBPM, JBoss Rules, Ajax4jsf, RichFaces, Facelets, Spring, iText, Quartz, TestNG etc.), and provides a single programming model for developers to "drive" those underlying frameworks via simple annotated POJOs (Plain Old Java Objects). It makes life easier for developers to tackle complex enterprise applications with many component frameworks.</para> + + <para>In this chapter, we will cover how to build a simple Seam web application in minutes with the Red Hat Developer Studio.</para> + + <section> + <title>Create a Seam Project</title> + + <para>To create a new web application in Seam, select "New > Project ... > Seam > Seam Project". You will be prompted to enter a name and a location directory for your new project. You will also be asked to choose a JBoss AS server to deploy the project. You must choose the JBoss AS 4.2.0 instance we had defined in the JBoss AS Server manager view.</para> + + <figure> + <title>Create a Seam project</title> + <mediaobject> <imageobject> - <imagedata fileref="images/StoppingServer.png"/> + <imagedata fileref="images/SeamNewProj01.png"/> </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>To create a Seam project, select <emphasis>Seam Gen > Setup/Configuration > Setup </emphasis>to -launch the Seam Gen setup window as shown below. Note: </listitem> -</itemizedlist> -<note> - <title>Note:</title> - <para>If this is the first time you run -Seam Gen a file dialog will be shown. In this diallog you need to select &lt;seam&gt;/seam-gen/build.xml - so the plugin knows which seam-gen to use.</para> - </note> -<para></para> - - <figure> -<title>Seam Gen Setup Window</title> -<mediaobject> + </mediaobject> + </figure> + + <para>Next, you will be asked to select the "features" you want to use in your project. This allows Red Hat Developer Studio to setup the appropriate tooling for your project. Since JBoss Seam integrates all popular Java EE frameworks, you can select any combination of technologies from the list. Here, for this project, we will select Dynamic Web Module, Java, Java Persistence (JPA), JavaServer Faces (JSF), and Seam Facet for a typical database-driven web application.</para> + + <figure> + <title>Select toolings for the project</title> + <mediaobject> <imageobject> - <imagedata fileref="images/SeamGenSetup.png"/> + <imagedata fileref="images/SeamNewProj02.png"/> </imageobject> -</mediaobject> -</figure> -<para>Fill the items in the dialog as shown below and select the <emphasis>OK</emphasis> button.</para> -<table> - <title>Filling Project Items</title> - <tgroup cols="2"> - <thead> - <row> - <entry>Field Name</entry> - <entry>Field Value</entry> - </row> - </thead> - <tbody> - <row> - <entry>Project</entry> - <entry>SeamSample</entry> - </row> - <row> - <entry>Seam project workspace</entry> - <entry>&lt;your project directory&gt;</entry> - </row> - <row> - <entry>JBoss AS Home directory</entry> - <entry>&lt;JBoss AS Home Dir&gt;</entry> - </row> - <row> - <entry>Driver Location</entry> - <entry>&lt;seam>/&lt;seam-gen&gt;/lib/hsqldb.jar</entry> - </row> - </tbody> - </tgroup> - </table> - <para>The plug-in will initialize the Seam Gen ant tasks that simplify all key Seam - operations. We will invoke several of these ant tasks via the Seam Red Hat Developer Studio Plugin - throughout this tutorial.</para> - <para>The plug-in will also prompt you to create a project. Select &quot;Yes&quot; to create a - Project. This step will create not only an Eclipse project but also all the required - artifacts to get you started.</para> - <para>The plug-in will also prompt you create a database connection. Select - &quot;Yes&quot; to create a WTP Database connection that connects to the default HSQL DB - instance that we have set up. If you are using any other database then set up the - appropriate database settings in the Seam Gen setup window.</para> - <para>At the end of this step you will see an Eclipse project called &quot;SeamSample&quot; - as shown below. This project has all the necessary elements required to deploy - a Seam application.</para> - <figure> -<title>SeamSample Project Structure</title> -<mediaobject> + </mediaobject> + </figure> + + <para>A dynamic web application contains both web pages and Java code. The wizard will ask you where you want to put those files. You can just leave the default values.</para> + + <figure> + <title>Select directory names for web pages and Java files</title> + <mediaobject> <imageobject> - <imagedata fileref="images/EclipseConProjectStructure.png"/> + <imagedata fileref="images/SeamNewProj03.png"/> </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Start the application server. Open your favorite browser and point to the -following URL http://localhost:8080/SeamSample. You should see the following page:</listitem> -</itemizedlist> -<figure> -<title>Created Project</title> -<mediaobject> + </mediaobject> + </figure> + + <para>Since you selected JPA and JSF tooling support, the project needs to incorporate the JAR files for those frameworks on its classpath. In the next two screens, you will be able to select where those library JARs come from. The easiest is just to select the JARs provided by the JBoss AS runtime associated with this project. That is why it is important to chose the right JBoss AS 4.2 runtime in the project setup window.</para> + + <para>Ignore the database selection for now since we do not use an external database in this simple application. We can still use the embedded HSQL DB inside JBoss AS for development / testing purposes, as we will see soon.</para> + + <figure> + <title>Select provider for JPA JARs</title> + <mediaobject> <imageobject> - <imagedata fileref="images/CreatedProject.png"/> + <imagedata fileref="images/SeamNewProj04.png"/> </imageobject> -</mediaobject> -</figure> -<para>Congratulations! You have written your first Seam application.</para> -<itemizedlist continuation="continues"> -<listitem>Let us take a look at the database connection that was created by Red Hat Developer Studio and browse the database provided. The database connection view should now have a - connection to our sample database as shown below.</listitem> - </itemizedlist> - <figure> -<title>Connections View</title> -<mediaobject> + </mediaobject> + </figure> + + <figure> + <title>Select provider for JSF JARs</title> + <mediaobject> <imageobject> - <imagedata fileref="images/ConnectionsView.png"/> + <imagedata fileref="images/SeamNewProj05.png"/> </imageobject> -</mediaobject> -</figure> -<para>Right click on the connection > Connect. Just specify &quot;sa&quot; as the user id. The password - field should be blank.</para> - <para>You should now be able to browse the database and see the meta-data and query data using SQL. - Your meta-data should look like the following:</para> - <figure> -<title>Meta-data View</title> -<mediaobject> + </mediaobject> + </figure> + + <para>The project setup wizard also asks you to configure how Seam generates code for the project. The Seam Home Folder should point to a valid Seam distribution. By default, it is set to the Seam distribution bundled in your Red Hat Developer Studio tool. For the deployment format, choose WAR deployment if you want to use POJOs for UI event handling and business logic; choose EAR deployment if you want to EJB3 beans for added features. In most web applications, the WAR deployment option would suffice. You should also enter Java packages for the entity beans (for database mapping) and session beans (for action handlers). All generated code will be placed in those packages. </para> + + <figure> + <title>Enter Java packages for generated code</title> + <mediaobject> <imageobject> - <imagedata fileref="images/Metadata.png"/> + <imagedata fileref="images/SeamNewProj06.png"/> </imageobject> -</mediaobject> -</figure> -</section> -<section id="GeneratingACRUDApplicationUsingSeamGen"> -<?dbhtml filename="GeneratingACRUDApplicationUsingSeamGen.html"?> -<title>Generating a CRUD application using Seam Gen</title> -<itemizedlist> -<listitem>The next step in our exercise is to generate a full blown application using Seam Gen. -This application will generate CRUD pages and Search pages for all the entities in the database. -Click on Seam Gen > Generate Entities. Seam Gen will connect to the database we defined in the - setup part of the application and generate all the required components.</listitem> - <listitem>Since Seam Gen is generating files on the file system that Eclipse does not know - about, right click on the project name on your project and choose the Refresh item. This will let - Eclipse know that there are new files and get them updated in the Eclipse project and deployed - in the JBoss instance.</listitem> - <listitem>Restart you application server, just in case those files have not been properly - synchronized with the application server.</listitem> - <listitem>Point your favorite browser to the following URL http://localhost:8080/SeamSample. - You will see the following page:</listitem> - </itemizedlist> + </mediaobject> + </figure> + + <para>Click on Finish to generate the application. The generated project contains all the necessary library JARs, XML configuration files, the ANT build script, as well as simple XHTML web pages and Java classes for the skeleton web application.</para> + <figure> -<title>SeamSample Project</title> -<mediaobject> + <title>The generated Seam web application</title> + <mediaobject> <imageobject> - <imagedata fileref="images/CreatedProject12.png"/> + <imagedata fileref="images/SeamNewProj07.png"/> </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Let us now look at one of the entities and see what has been generated. Click on the - &quot;Offices List&quot; to see a search page that allows you to filter the list and the list of all the - offices in the database.</listitem> - <listitem>Type in USA in the country field and click on Search to get a list of offices in the - USA as shown below.</listitem> - </itemizedlist> - <figure> -<title>Search Panel</title> -<mediaobject> + </mediaobject> + </figure> + + </section> + + <section> + <title>Build and Deploy the Seam Application</title> + + <para>Once the application is generated, you can use the "Run on server" menu to build and deploy it into the JBoss AS runtime associated with the project. All you need is to start JBoss AS in the server manager, and load the browser at URL http://127.0.0.1:8080/MySeamProj/. You should see the following web page.</para> + + <figure> + <title>The generated application in action</title> + <mediaobject> <imageobject> - <imagedata fileref="images/SearchPanel.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> - -<itemizedlist continuation="continues"> -<listitem>Let us now check out the editing capability of the generated Seam application. Select - the first office code and click on the Edit button. You will be prompted for a userID and - password. Use &quot;seamuser&quot; for both user and password. You should at this point see the edit page - as shown below. Notice that the NOT NULL columns in the database table are automatically marked - with the red * to indicate that they are required.</listitem> - </itemizedlist> - <figure> -<title>Generated Edit Page</title> -<mediaobject> + </mediaobject> + </figure> + + <para>To make simple changes to the page, you just need to double click on the view/index.xhtml file and edit it in the visual editor. Notice that the visual editor lets you both the XHTML code and the rendered page. The rendered view is designed to make it easy to find stuff in a complex XHTML page.</para> + + <figure> + <title>Making changes in the visual editor</title> + <mediaobject> <imageobject> - <imagedata fileref="images/GeneratedEditPage.png"/> + <imagedata fileref="images/SeamJsfEditor.png"/> </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Change a few things and save changes. This should update the record in the database. - There you have it. A simple and easy way to bootstrap your applications.</listitem> - <listitem>Let us look at how validations are done in Seam. Go back to and edit another office - record and this time leave the city blank and click on the Save button. You will see the default - Seam validations get triggered. In this case the &quot;value required&quot; validation is fired as shown - below.</listitem> - </itemizedlist> -<figure> -<title>Error Reporting</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/ValidationInEditPage.png"/> - </imageobject> -</mediaobject> -</figure> -</section> -<section id="CustomizingTheGeneratedApplication"> -<?dbhtml filename="CustomizingTheGeneratedApplication.html"?> -<title>Customizing the generated application</title> -<itemizedlist> -<listitem>Let us look at a couple of simple things we can change in the generated application - to show you that the generated application can be customized. Let us start by changing the edit - page that we just saw. We will clean up the labels using the Facelet designer as shown below. - Open the view directory in your project and double click on the OfficeEdit.xhtml file.</listitem> -</itemizedlist> -<figure> -<title>Facelet Designer</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/FaceletDesigner.png"/> - </imageobject> -</mediaobject> -</figure> -<para>Unlike other WYSIWYG editors which developers tend to hate, the visual designers in Red Hat - Developer Studio are designed for developers to rapidly find their way in a source file, while - still allowing them to visually look at a document.</para> - -<itemizedlist continuation="continues"> -<listitem>To change a label text, click on a label in the designer. This will position the - cursor at the correct location in the source view. Type the new label there. The designer does - not force the developer to use the WYSIWIG environment. Change all the labels for the edit page.</listitem> - </itemizedlist> - <para>Once you save the page, the IDE automatically rebuilds the application and re-deploys it. - So, just reload your browser and you should see an updated web page like the following. If for - some reason the re-deployment did not work, stop and restart the server normally resolves the issue.</para> + </mediaobject> + </figure> + + <para>Once you finished editing, save the file (File > Save), re-deploy the application, and reload the browser to see the changes.</para> + <figure> -<title>Edit Page</title> -<mediaobject> + <title>The front page is changed</title> + <mediaobject> <imageobject> - <imagedata fileref="images/EditPage.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> -</section> -<section id="UsingHibernateToolsToInteractWithTheJPAEntities"> -<?dbhtml filename="UsingHibernateToolsToInteractWithTheJPAEntities.html"?> -<title>Using Hibernate tools to interact with the JPA Entities</title> -<para>As part of generating the application, Seam Gen also generates JPA entities that are used - to interact with the database. Let us quickly take a look at Hibernate tools and see how we can - interact with the database using HQL and the Hibernate Criteria API.</para> - <itemizedlist> - <listitem>Open the Hibernate Configurations View. You should be able to open the console like - the other views we have seen so far in the tutorial. Your view should resemble the following:</listitem> - </itemizedlist> - <figure> -<title>Hibernate Configurations View</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HibernateConfigurationsView.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Before we run the HQL, let us open up the &quot;Hibernate Query Result&quot; and the &quot;Hibernate - Dynamic SQL Preview&quot; views. You should be able to do that in a manner similar to other views we - have opened in this tutorial. Alternatively you can open the Hibernate Console Perspective where - these views are opened up by default.</listitem> - <listitem>Click on the &quot;HQL&quot; icon in the &quot;Hibernate Configurations&quot; view. This will open up - the HQL Designer view as shown below. Also, select &quot;SeamSample&quot; from the drop down menu next to - the green &quot;run&quot; button.</listitem> - </itemizedlist> + </mediaobject> + </figure> + + <!-- Not yet ... + <para>Notice that we do not need to re-build and re-deploy the application. Just save the edited page and reload the browser.</para> + --> + + </section> + + <section> + <title>Add a Web Page and an Action</title> + + <para>To add a new page and related UI action to the project, use the "New > Other ... > Seam > Seam Form" wizard. You are prompted to enter the name of the web page, the name for the Seam component that handles UI actions from the page, and UI action method name.</para> + <figure> -<title>HQL Designer View</title> -<mediaobject> + <title>New form for the application</title> + <mediaobject> <imageobject> - <imagedata fileref="images/HQLDesignerView.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Type in a simple query as shown above &quot;from Offices o&quot; and click on the green &quot;run&quot; - button. You should see the result of the HQL query in the &quot;Hibernate Query Result&quot; window as - shown below.</listitem> - </itemizedlist> + </mediaobject> + </figure> + + <para>The wizard generate a web page with a single text input field and an action button. Notice that the generated page uses layout/template.xhtml as a template. The template page provides the page header, footer, side menu, and CSS styles (see the template.xhtml for more details). The Simplepage.xhtml is assembled into the template when the Simplepage.seam URL is loaded.</para> + + <programlisting role="JSP"><![CDATA[ +<!DOCTYPE composition PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + + xmlns:s="http://jboss.com/products/seam/taglib" + xmlns:ui="http://java.sun.com/jsf/facelets" + xmlns:f="http://java.sun.com/jsf/core" + xmlns:h="http://java.sun.com/jsf/html" + template="layout/template.xhtml"> + +<ui:define name="body"> + + <h1>Simplepage</h1> + <p>Generated form page</p> + + <h:messages globalOnly="true" styleClass="message"/> + + <h:form id="simpleAction"> + <div class="dialog"> + <s:validateAll> + <div class="prop"> + <span class="name">Value</span> + <span class="value"> + <s:decorate> + <h:inputText id="value" required="true" + value="#{simpleAction.value}"/> + </s:decorate> + </span> + </div> + </s:validateAll> + </div> + <div class="actionButtons"> + <h:commandButton id="hello" value="hello" + action="#{simpleAction.hello}"/> + </div> + </h:form> + +</ui:define> + +</ui:composition> +]]></programlisting> + + <para>The #{simpleAction.value} notation on the web page maps to the "value" property in the backend component named "simpleAction", and the #{simpleAction.hello} notation indicates that the hello() method is called when the button is clicked on. Here is the "simpleAction" named backend Seam component generated by the wizard.</para> + + <programlisting role="JAVA"><![CDATA[ +@Name("simpleAction") +public class SimpleAction { + + @Logger private Log log; + + @In + FacesMessages facesMessages; + + private String value; + + //seam-gen method + public String hello() + { + //implement your business logic here + log.info("simpleAction.echo() action called with: #{simpleAction.value}"); + facesMessages.add("echo #{simpleAction.value}"); + return "success"; + } + + //add additional action methods + + @Length(max=10) + public String getValue() + { + return value; + } + + public void setValue(String value) + { + this.value = value; + } + +} +]]></programlisting> + + <para>Load the Simplepage.seam in the web browser. Type something in the text field and click on the "hello" button. A JSF message containing the input string is created by the SimpleAction.hello() method. The message is displayed on the page via the h:messages tag.</para> + + </section> + + <section> + <title>Input Validation</title> + + <para>Notice that in the generated SimpleAction class, there is a @Length annotation to validate the input when the input string is bound to #{simpleAction.value}. To see how this works, enter a text string longer than 10 chars and click on the button. This is what you should see.</para> + <figure> -<title>Hibernate Query Result Window</title> -<mediaobject> + <title>The input validation in action</title> + <mediaobject> <imageobject> - <imagedata fileref="images/HibernateQueryResultWindow.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Click on any of the objects in the result and you should be able see the contents of - the objects in the Property view as shown below. If you don&apos;t have the view open in your - perspective, you can open this view like all other views in this tutorial.</listitem> - </itemizedlist> + </mediaobject> + </figure> + + <para>Seam supports many different input validation annotations. To see an example, you can replace the @Length(max=10) annotation with the following. It would require the input string to have a first name and last name separated by a space. If the validation fails, the web page would print the customized error message.</para> + + <programlisting role="JAVA"><![CDATA[ +@NotNull +(a)Pattern(regex=&quot;^[a-zA-Z.-]+ [a-zA-Z.-]+", + message="Need a firstname and a lastname") +public String getValue() +{ + return value; +} +]]></programlisting> + + <para>Save the Java file, deploy the application, and reload the browser to see the new validation scheme in action.</para> + <figure> -<title>Property View</title> -<mediaobject> + <title>More input validation</title> + <mediaobject> <imageobject> - <imagedata fileref="images/PropertyView.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> -<para>Select the &quot;Hibernate Dynamic SQL Preview&quot; view to the generated SQL. This is a great tool -to see the SQL being generated by Hibernate for your HQL. Not only is this a great debugging tool, - it is also a great way to optimize your HQL queries.</para> - <figure> -<title>Hibernate Dynamic SQL Preview</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/HibernateDynamicSQLPreview.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Let us try a slightly more complex query. Type in the following query in the query -window and see how the query result changes and the SQL Preview changes.</listitem> - </itemizedlist> - <programlisting role="JAVA"><![CDATA[select city, state, postalcode - from Offices o - where country = 'USA' -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Let us try the Hibernate criteria APIs next. To use Hibernate Criteria APIs click on -the &quot;CRI&quot; button in the Hibernate Configurations View. This will open the Criteria API designer -view. Type in this simple criteria query as shown below and click on the green run button to see - the results. Also, select &quot;SeamSample&quot; from the drop down menu next to the green &quot;run&quot; button.</listitem> - </itemizedlist> - <programlisting role="JAVA"><![CDATA[session.createCriteria(Offices.class) -]]></programlisting> -<para>The results will be very similar to the HQL query except that the criteria query does not -generate the SQL in the &quot;Hibernate Dynamic SQL Preview&quot; view.</para> -<itemizedlist continuation="continues"> -<listitem>Let us try something a little more complex. Let us filter all offices in the USA as -shown below. The results of this query should be very similar to the results of the HQL.</listitem> - </itemizedlist> - <programlisting role="JAVA"><![CDATA[session.createCriteria(Offices.class) - .add(Restrictions.eq("country", "USA")) ; -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Finally let us visually see the entity model of the generated JPA objects. Before we - do that, open the &quot;Hibernate Entity Model&quot; view and select the &quot;Configurations&quot; option in the - &quot;Hibernate Configurations&quot; view. The plug-in will show all the entities in a visual format. - You can either manually align your objects or click on the &quot;Layout&quot; button on the right of the - &quot;Hibernate Entity Model&quot; view to generate a default layout.</listitem> - </itemizedlist> + </mediaobject> + </figure> + + </section> + + <section> + <title>Add a new UI Component</title> + + <para>Now, let's add a little more logic to the application. We will add a new boolean property to the action component. If it is set to true, the action would capitalize the input string and display it on the web page. The following code in the SimpleAction class implements the logic.</para> + + <programlisting role="JAVA"><![CDATA[ +@Name("simpleAction") +public class SimpleAction { + + private boolean convertToCap; + + public boolean getConvertToCap () { return convertToCap; } + public void setConvertToCap (boolean b) { convertToCap = b; } + + public String hello() + { + if (convertToCap) { + value = value.toUpperCase (); + } + return null; + } + ... ... +} +]]></programlisting> + + <para>Next, on the web page, add the following line to display the value property on the simpleAction component. Notice that code completion is supported for the JSF EL expression.</para> + + <programlisting role="JSP"><![CDATA[ +<p><b>Hello, #{simpleAction.value}</b></p> +]]></programlisting> + + <para>Finally, on the web page, we add a boolean selection box component. It is bound to the XXXX property on the backend component.</para> + + <programlisting role="JSP"><![CDATA[ +<h:selectBooleanCheckbox title="convertToCap" + value="#{simpleAction.convertToCap}" /> +Capitalize the input? +]]></programlisting> + + <para>Deploy the application and see it in action now.</para> + <figure> -<title>Hibernate Entities</title> -<mediaobject> + <title>Add UI components and business logic</title> + <mediaobject> <imageobject> - <imagedata fileref="images/HibernateEntities.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> - -</section> -<section id="AddingAJAXAndRichUIFeaturesToASeamApplication"> -<?dbhtml filename="AddingAJAXAndRichUIFeaturesToASeamApplication.html"?> -<title>Adding AJAX and rich UI features to a Seam application</title> -<para>A key feature of JBoss Seam and the Red Hat Developer Studio is that they make AJAX and rich - UI web applications a breeze to develop. In this section of the tutorial, we will show you how - to:</para> - <itemizedlist> - <listitem>Add AJAX features to automatically generated JSF Seam UI components</listitem> - <listitem>Replace standard JSF UI components with AJAX enabled rich UI components provided by the - Red Hat Developer Studio</listitem> - <listitem>Use AJAX components to do live validation on web pages</listitem> - </itemizedlist> - <section id="AddingAJAXFeaturesToGeneratedUIComponents"> -<?dbhtml filename="AddingAJAXFeaturesToGeneratedUIComponents.html"?> -<title>Adding AJAX features to generated UI components</title> -<para>Let us now try to add some AJAX features to the generated Seam application. Click on the - Payments List link on the top of the page. You will see a search page as shown below.</para> - <figure> -<title>Search Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/SearchPage.png"/> - </imageobject> -</mediaobject> -</figure> -<para>You can search for any &quot;checknumber&quot; by typing in the number or by paging through the list - of payments. But what if you only knew a few of the digits/alphabets in the &quot;checknumber&quot;? It - would be very useful to filter the list based on that. AJAX provides very useful techniques to - build these types of applications and Ajax4jsf provides the building blocks to simplify these - techniques.</para> - <para>Double Click on the PaymentsList.xhtml to open the visual facelet designer. You will - notice that in the beginning of the source, Seam Gen has already add the tag library references - to Ajax4jsf and RichFaces as shown below.</para> - <programlisting role="JAVA"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:f="http://java.sun.com/jsf/core" - xmlns:h="http://java.sun.com/jsf/html" - xmlns:a4j="https://ajax4jsf.dev.java.net/ajax" - xmlns:rich="http://richfaces.ajax4jsf.org/rich" - template="layout/template.xhtml"> -]]></programlisting> -<para>Next, locate the check number input field. We need to add AJAX to this field. Basically, -as we type we want to update the table. Adding AJAX functionality usually requires two things:</para> -<itemizedlist> -<listitem>Letting the framework know on which event to send an AJAX request to the server.</listitem> -<listitem>Specifying what component(s) to update with the output from the server.</listitem> -</itemizedlist> -<para>Ajax4jsf provides a simple JSF component <emphasis role="bold"><property>&lt;aj4:support&gt;</property></emphasis> that simplifies this process. Let us -take our example and add AJAX to it.</para> -<itemizedlist> -<listitem>Click on the checknumber field in the visual designer, it will position you at the -correct location in the source. You will notice that the inputText tag does not have a closing -tag. Let us add a closing tag to the input text field as shown below.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<h:inputText id="checknumber" - value="#{paymentsList.payments.checknumber}"> - <a4j:support event="onkeyup" reRender="paymentsList"/> - </h:inputText> -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Now let us add the AJAX support tag to let Ajax4jsf know that when the user presses a - key we want to go to the server to get a list of payments that match the characters entered in - the checknumber text box. Add the tag that is highlighted below to the inputText tag.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<h:inputText id="checknumber" - value="#{paymentsList.payments.checknumber}"> - <a4j:support event="onkeyup" reRender="paymentsList"/> - </h:inputText> -]]></programlisting> -<para>This tag is pretty self explanatory, it posts the server when a key is pressed and then - takes the response from the server and re-renders the section of the page that has an id of - &quot;paymentsList&quot;.</para> - <itemizedlist continuation="continues"> -<listitem>If you follow along in the page, you will see that the section that displays the -results is in a div tag that has an id of &quot;paymentsList&quot;</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<div class="results" id="paymentsList"> - <h3>search results</h3> - <h:outputText value="No payments exists" - rendered="#{empty paymentsList.resultList}"/> - ... - </div> -]]></programlisting> -<itemizedlist continuation="continues"> -<listitem>Save the changes and refresh your browser. You will see that as you type characters -in the checknumber field, all payments that begin with those characters will be displayed in the -table automatically.</listitem> -</itemizedlist> -<figure> -<title>Data Fields</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/DataFields.png"/> - </imageobject> -</mediaobject> -<mediaobject> - <imageobject> - <imagedata fileref="images/Buttons.png"/> - </imageobject> -</mediaobject> -</figure> -<para>But there is still one more problem in this page, you will see that the &quot;Next&quot; and - &quot;Previous&quot; buttons will be displayed even for search results that are small as shown above.</para> - <itemizedlist continuation="continues"> -<listitem>The tag that we added in the previous step only updates the table. Let us add an AJAX -region around the page buttons at the bottom of the table. This will allow Ajax4jsf to update -those buttons independently.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<a4j:outputPanel ajaxRendered="true"> - <div class="tableControl"> - ... - </div> - </a4j:outputPanel> -]]></programlisting> -<para>Add an <emphasis role="bold"><property>&lt;a4j:outputPanel&gt;</property></emphasis> tag around the page buttons as shown above and run the page again. - If the result list is small, you will see that the page buttons are no longer visible as shown - below.</para> - <figure> -<title>Datatable With No Page Buttons</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/NoButtons.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Let add one more thing to complete this part of the sample. When we type a character in - the &quot;checknumber&quot; field, there is no visual feedback to the user that there is a request being - made to the server.</listitem> - </itemizedlist> - <para>Ajax4jsf has a pre-built tag <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> that allows you to either render a text or an - image in response to an AJAX event. Add the following code, right after the end of the - <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> tag.</para> - <programlisting role="JSP"><![CDATA[<a4j:status> - <f:facet name="start"> - <h:graphicImage value="/img/ajax-loader.gif" style="border: 1px solid #E0E0E0"/> - </f:facet> - </a4j:status> -]]></programlisting> -<para>Save changes to the page and refresh the browser. You will see the image when the AJAX -request is active. The image will disappear as soon as the response is received.</para> -<itemizedlist continuation="continues"> -<listitem>Finally, let us place the image beside the &quot;checknumber&quot; text box. Place a -<emphasis role="bold"><property>&lt;h:panelGroup&gt;</property></emphasis> around the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> and <emphasis role="bold"><property>&lt;a4j:status&gt;</property></emphasis> tags as shown below. -Save changes and refresh the browser. You should see the image right next to the text box.</listitem> - </itemizedlist> - <programlisting role="JSP"><![CDATA[<h:panelGroup> - <h:inputText id="checknumber" - value="#{paymentsList.payments.checknumber}"> - <a4j:support event="onkeyup" - reRender="paymentsList"/> - </h:inputText> - <a4j:status> - <f:facet name="start"> - <h:graphicImage value="/img/ajax-loader.gif" - style="border: 1px solid #E0E0E0"/> - </f:facet> - </a4j:status> - </h:panelGroup> -]]></programlisting> -<para>Although this example was a bit long, it shows how easy it is to add AJAX capabilities to -an existing Seam application.</para> -</section> -<section id="AddingRichfacesComponentsToaSeamApplication"> -<?dbhtml filename="AddingRichfacesComponentsToaSeamApplication.html"?> -<title>Adding RichFaces components to a Seam application</title> -<para>Now that we have seen how AJAX can bring interactivity to an application, let us add rich -controls that will improve the user experience. RichFaces provides numerous rich controls that -can be added to an application. In this section we will add spinner and slider controls that -allow users to change numerical values without using the keyboard.</para> -<para>Double Click on the OrderdetailsEdit.xhtml to open the visual facelet designer. You will - notice that in the beginning of the source, Seam Gen has already included the tag library - references to Ajax4jsf and RichFaces as shown below.</para> - <programlisting role="JSP"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml" - xmlns:s="http://jboss.com/products/seam/taglib" - xmlns:ui="http://java.sun.com/jsf/facelets" - xmlns:f="http://java.sun.com/jsf/core" - xmlns:h="http://java.sun.com/jsf/html" - xmlns:a4j="https://ajax4jsf.dev.java.net/ajax" - xmlns:rich="http://richfaces.ajax4jsf.org/rich" - template="layout/template.xhtml"> -]]></programlisting> -<para>In this page, we are going to replace the &quot;quantityordered&quot; text box with the spinner - control.</para> - <itemizedlist> - <listitem>In the visual view of the page, click on the &quot;quantityordered&quot; text box, this will - select the appropriate markup in the source view. Delete the selected markup.</listitem> - </itemizedlist> - <figure> -<title>Deleting Selected Markup</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/DeletingSelectedMarkup.png"/> - </imageobject> -</mediaobject> -</figure> -<para>We will replace the <emphasis role="bold"><property>&lt;h:inputText&gt;</property></emphasis> tag with a pre-built <emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> tag. - The spinner control tag is very simple to use and like all other JSF controls, it has a value - attribute that can be bound to any JSF Managed Bean or Seam component. The designer allows you - to visually find all the beans available as shown below. Right - click on the <emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> input field and select &quot;<emphasis role="bold"><property>&lt;rich:inputNumberSpinner&gt;</property></emphasis> Attributes&quot;.</para> + </mediaobject> + </figure> + + </section> + + <section> + <title>Add Security to the Application</title> + + <para>You have probably noticed that the web page template has a login link at the top of the page. You can use the Seam security framework to secure access to any web page or web action. You can implement the login logic in the XXXX method. In the following example, we just use hardcoded username and password. But you can easily change it to use database, LDAP or any other means.</para> + + <programlisting role="JAVA"><![CDATA[ +]]></programlisting> + + <para>Then, on the action method, you can use the XXXX annotation to specify that it is only invoked by authenticated users.</para> + + <programlisting role="JAVA"><![CDATA[ +]]></programlisting> + + <para>Now, re-deploy the application and try the XXXX button. The application redirects to the XXXX page asking for login credentials. The method is invoked after you successfully logged in.</para> + <figure> -<title>Replacing Tags</title> -<mediaobject> + <title>Access control for action methods</title> + <mediaobject> <imageobject> - <imagedata fileref="images/ReplacingTags.png"/> + <imagedata fileref="images/xxxx.png"/> </imageobject> -</mediaobject> -</figure> -<para>The minValue and maxValue are self explanatory, they represent the minimum and maximum - values for the spinner. Place the following tag in your page.</para> - <programlisting role="JSP"><![CDATA[<rich:inputNumberSpinner - value="#{orderdetailsHome.definedInstance.quantityordered}" - inputStyle="width:30px; height:20px" - minValue="0" - maxValue="100" - required="true"/> -]]></programlisting> + </mediaobject> + </figure> + + <para>We can also secure web pages. You can edit the XXXX file to put an access constraint on the XXXXX page.</para> + + <programlisting role="JSP"><![CDATA[ +]]></programlisting> + + <para>You can try to load the XXXX URL in the browser and it will redirect to ask for login.</para> + + </section> + -<itemizedlist continuation="continues"> -<listitem>Save changes and refresh the browser page. Your output page should look like this:</listitem> -</itemizedlist> -<figure> -<title>Output Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OutputPage.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Although this is not the best situation to use a slider, let us take a quick look at -another RichFaces control <emphasis role="bold"><property>&lt;rich:inputNumberSlider&gt;</property></emphasis>. The slider control is similar to the the -spinner control; it is bound to the same object. Replace the spinner with the following markup. -Save the page and refresh your browser window.</listitem> -</itemizedlist> -<programlisting role="JSP"><![CDATA[<rich:inputNumberSlider - value="#{orderdetailsHome.definedInstance.quantityordered}" - styleClass="slider" - width="200"/> -]]></programlisting> -<figure> -<title>InputNumberSlider Settings</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/InputNumberSliderSettings.png"/> - </imageobject> -</mediaobject> -</figure> -<itemizedlist continuation="continues"> -<listitem>Seam Gen also generates a date picker control for all date fields in an edit page. - Click on &quot;Order List&quot; and edit one of the orders to see an example of the date picker control - that is bundled with Seam.</listitem> -</itemizedlist> - -<figure> -<title>Order List</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OrderedList.png"/> - </imageobject> -</mediaobject> -</figure> - -</section> -<section id="ValidatingTheAJAXWay(LiveValidations)"> -<?dbhtml filename="ValidatingTheAJAXWay(LiveValidations).html"?> -<title>Validating the AJAX way (Live Validations)</title> -<para>Seam Gen also generates field validation code that leverages AJAX techniques, by providing - immediate feedback to users who use these applications. To see an example of this, go back to - the Office Edit page and leave the city blank and tab out of the field. Seam will immediately - validate the field and tell you that the value is required.</para> - <figure> -<title>Office Edit Page</title> -<mediaobject> - <imageobject> - <imagedata fileref="images/OfficeEditPage.png"/> - </imageobject> -</mediaobject> -</figure> -<para>To provide this functionality for every required field in the page Seam generates the - following markup:</para> -<programlisting role="JSP"><![CDATA[<s:decorate id="cityDecoration"> -<h:inputText id="city" - required="true" - size="50" - maxlength="50" - value="#{officesHome.instance.city}"> - <a:support event="onblur" reRender="cityDecoration"/> - </h:inputText> - </s:decorate> -]]></programlisting> -<para>Seam uses Ajax4jsf to make a server side call to validate the field.</para> -</section> -</section> - <section id="OtherRelevantResourcesOnTheTopic2"> <?dbhtml filename="OtherRelevantResourcesOnTheTopic2.html"?> <title>Other relevant resources on the topic</title>