Tutorial – Creating your first application 

---

This is the second of four tutorials that introduce you to the many powerful features of IBM® WebSphere® Portlet Factory. In this tutorial, you will build a simple "hello world" application.

Using these tutorials

This set of tutorials are a great starting point for a new WebSphere Portlet Factory developer. Each of the four parts of this tutorial take between 30 and 45 minutes to complete. The tutorials should be completed in the following order, as each builds on knowledge obtained in the previous tutorial. In addition, we recommend visiting the WebSphere Portlet Factory Learning Roadmap on the WebSphere Portlet Factory wiki after completing these tutorials to further advance your WebSphere Portlet Factory learning experience.

Table 1.

Tutorial order	Description
Creating a Web Application Project	In this tutorial you will learn how to create a web application project.
Creating an application	In this tutorial, you will build a simple "hello world" application and then create a portlet from that application.
Creating a database application	In this tutorial you will create a service provider model against a sample database using the SQL Table Create builder, and then create a user interface service consumer model, using the Service Consumer and Data Services User Interface builder.
Using profiling in your new application	Continuing from the "hello world" application tutorial you add the power of profiling to your application.

What you will learn

Developers build applications by creating a model, adding builders to those model, running the application you had just created, and then create a portlet from that application.

Setup Requirements

The following setup is required to run the tutorial.

• You need to have created and published a project. The project must include the "Tutorials and Samples / Applications" feature set. Creating a project is described in detail in the tutorial called "Creating a Web Application Project".
• WebSphere Portal server must be running.
  

Create your first application

1. In this part of the tutorial, we will create a new WebSphere Portlet Factory model.
1. Launch WebSphere Portlet Factory Designer.
2. Open the MyFirstProject WebApp project you created in the "Creating a Web Application Project" tutorial.
3. Choose File -> New -> WebSphere Portlet Factory Model. This command will invoke a wizard to assist you in creating a new model.
4. Choose the project in which this model should be created. The MyFirstProject WebApp project should be highlighted. Click Next to continue.
5. When creating a new model, you can choose from a list of starter models. In the Select Model page, choose Main and Page from the Factory Starter Models category and click Next.The Page Settings dialog displays.
6. Since you have chosen the Main and Page starter model, you get the option to specify what the contents of the first page should be. You can choose an existing HTML file or choose Simple Page to get a very basic HTML page. Choose Simple Page and click Next. The Save New Model dialog displays.
7. Models are saved under the models folder in the project. Since this project already contains the Samples and Tutorials feature set, there are some tutorial-related folders you should use. Expand the models folder and choose the folder called models\\tutorials and enter MyFirstPortlet and click Finish. WebSphere Portlet Factory Designer will now create your new model and open it for you.
   
What is a model?
A model is simply a set of calls to builders, which in turn generate the application components representing the behavior, structure, data, and presentation of the application. Underneath the covers, a model is simply an XML file containing a series of calls to builders.

When you want to create a new application, you will create a new model, and then add the appropriate builder calls to the model.

2. Examine and run the new model
1. In the lower left corner of the workspace, there is a tab labeled Outline which contains the all the builders that the model uses, or the model's "builder call list". Models are constructed from builders, and each builder in a model is represented by a builder call. Builder calls can be edited by double-clicking them in the builder call list.
   
What is a builder?
A builder is a highly adaptive software component that generates code (including Java, JSP, and XML) for specific application functionality. For example, WebSphere Portlet Factory provides builders that are as simple as automating the creation of the code to place a button on a web page. WebSphere Portlet Factory also includes many powerful builders like the Data Services User Interface builder, which creates all the necessary variables, JSP, schemas, and Java code needed to create an entire application that retrieves and displays data from a data source (database, Lotus Domino, web service, variable, and so on).

Builders have easy-to-use, wizard-like user interfaces, which make it both fast and easy to develop applications. Builders, however, are much more powerful than wizards, since builders can be used iteratively throughout the entire development process. Unlike other IDEs which provide run-once Wizards, with WebSphere Portlet Factory you can always go back and change a builder's input values, and have the entire application update instantly.

Behind the scenes, a builder is made up of a Java class that performs the appropriate automation task (like creating the JSP for the button) and an XML document (builder definition) that defines the builder's inputs, and design time user interface characteristics.

2. In the builder call list, double-click the action list builder call named main. The builder call editor will open to the right and will show the current values of that builder's inputs. As you can see, there is only one element in the action list. That action triggers the page called page1 to be displayed.
3. Now, in the builder call list, double-click the Page builder call named page1. It contains some very basic HTML with some named <span> tags. Portlet Factory uses named tags (html elements with a name attribute) to location the position on the page where generated user interface markup should be placed. Right now, this page simply displays the simple HTML you can see in the Page Contents field.
4. Run the model by clicking from the row of icons immediately below the menu at the top of the workspace. A browser launches and display this simple application containing a simple page titled "Default Test Page".
5. Close the browser and return to WebSphere Portlet Factory Designer.
   
3. In this part of the tutorial we will construct a basic page layout
1. What is shown in the Application Tree?
The Application tree shows all of the artifacts that are generated by the builders in the current model. It allows you to select these artifacts to show details about the object. These can be Java, XML, HTML, JSP etc. There are a couple of ways to see the details of an object. The Source tab shows a text representation of what was created and the Design tab shows a visual representation of the object. The Design tab is not exactly what will render in the browser when you run the application but it does help to preview many changes as you are creating your application. In addition to the static text in the HTML page, the Design tab also shows the named tags that do not currently have any content in them. Currently, the Design tab is only available for pages.
If the Application Tree is not visible, be sure you have the MyFirstPortlet model open and selected. If it is not, find the MyFirstPortlet model in the Project Explorer window and double-click it
Try choosing different elements in the Application Tree and watch for the corresponding elements in the Source and Design views become highlighted.

2. Add a Text builder call to the model to replace the <span> tag called namedTag..
1. Select page1 in the Application Tree.
2. Above the Application Tree, click to display a list of builders that can be added to this model. This list shows all available builders and their builder categories. The default selected category is Recommended which lists the builders that would be commonly used based on your current selection in the Application Tree. Since there are many builders that can modify a page, many choices are displayed.
3. Search and select Text as the type of builder call to add and click OK. This new builder call displays ihe builder call editor in the pane on the right.
4. The Page Location section of this builder call contains several inputs. Page and Tag contain drop-down lists of choices. Choose page1 for the Page field and namedTag for the Tag field. This Text builder will now know to replace the contents of the named <span> tag called namedTag with whatever text expression you specify in the Text input.
5. The input labeled Text is where you enter the text that this builder call will add to the page. Locate this input and enter Tutorial Basics – Hello World!.
6. Click OK.
7. Click on the design tab to see that the text builder that added the words Tutorial Basics – Hello World! . Run the model again and view it in a web browser. This time you will see that the phrase, Tutorial Basics - Hello World! has replaced the static text, "Use a named tag to place the results of a builder call on a page".
   
Note: You are using a text builder to get started very quickly with WebSphere Portlet Factory . In your normal development process, you will want to be using Data Page builders and page automation to really take advantage of the full power of WebSphere Portlet Factory. We will be explaining an using these feature in the tutorial that follow this

Turning the Application into a Portlet

To this point, you have created an application but you have not yet enabled the model to be a portlet. Now, you will enable the model to run within the WebSphere Portal framework as a portlet. This task is easy to accomplish because there is a builder for this purpose: the Portlet Adapter builder.

What is a Portlet Adapter builder?

A Portlet Adapter builder configures a model automatically so that it can function as a portlet in WebSphere Portal. Useful information for a portlet such as a name, title, a description, and optionally a portlet help file name is entered in a builder call of this type. The name, title, and description are visible to portal administrators when managing portlets and applying them to portal pages. Help files are accessed by users via the portlet title bar menu in the portlet.

We'll leave profiling for a more advanced tutorial, but point out here that the default user interfaces (UIs) for the Configure and Edit pages are fairly plain. Richer UIs for these pages can be created separately in individual HTML pages or WebSphere Portlet Factory models. These pages and models can be referred to in a Portlet Adapter builder call and the builder will automatically add them to the portlet.

You will add a Portlet Adapter builder call to the MyFirstPortlet model and test your work by adding the portlet to a portal page.

1. Enable the model to function as a portlet.
1. Open the MyFirstPortlet model.
2. Click to add a new builder call to the model. Choose the category All if not yet chosen.
3. Choose Portlet Adapter builder and click OK.
4. Use the following table for the details about what values to provide for the various inputs to this builder call. Click OK when you are finished entering these values.
   
Table 2. Portlet Adapter builder inputs

Input Name	Enter this value for the given input
Name	tutorial_basics
Portlet Title	Tutorial Basics – Portlet
Portlet Description	Simple example to demonstrate core concepts



5. Click OK.
6. Save the model.
7. Right-click the project's name and choose Publish Application. Select your Portal Server Configuration and Click OK. This task can take a few moments to complete.
   
Why republish the Portlet WAR?

A portlet Web Application Archive or WAR was created when you created the project in an earlier tutorial. As changes are made to the models and profile sets in the project, these changes get published on the portal server automatically.

Some changes to a model, however, require that the portlet WAR be republished. Adding a Portlet Adapter builder to a model is one of those changes. In order for the portal framework to be aware of the new portlet, the portlet WAR on the portal server must be replaced with a new one. Republishing the existing portlet WAR in WebSphere Portlet Factory Designer also automatically publishes the new WAR replacing the old one.

2. Create the WebSphere Portlet Factory work portal pages
   
To help you complete this tutorial and support other tutorials you may do later, in this step you will create a small hierarchy of pages under the My Portal -> My Work page in the portal.

1. Log into WebSphere Portal as an administrator.
2. Click the Administration link.
3. Click Portal User interface -> Manage Pages..
4. Find the link to the Content Root page and click it.
5. Click the New Page button and create a page called WebSphere Portlet Factory. Accept the default values and click OK. The WebSphere Portlet Factory page should now be in the list.
6. Click the link to the WebSphere Portlet Factory page. Create a new page called Tutorials. Click OK to save the page.
   
3. Create the Basics page and add MyFirstPortlet.
1. Click the link to the Tutorials page. Create a new page called Basics. Click OK to save the page.
2. Click on the Edit Page Layout icon on the line next to the Basics page details. The Edit Layout page displays.
3. Click on the Add Portlet icon.
4. Use the search feature to find the "Tutorial Basics – Portlet" portlet in the list.
5. Click on the checkbox next to the portlet and click OK and click Done to save your changes.
6. Click on the Home tab and then the WebSphere Portlet Factory tab
7. Navigate to Tutorials/Basics to view your imbedded "Hello World" portlet.
   

Lessons learned and next steps

WebSphere Portlet Factory is a powerful tool for developing portlets and J2EE-compliant web applications. Applications and portlets are constructed from builders. Each builder call in a model makes some contribution to the XML representation of the application WebSphere Portlet Factory is supposed to generate. Through the regeneration process, an application is produced.

Now, you are ready to complete the Tutorial - Creating a database application tutorial where you will create a service provider model against a sample database using the SQL Data Services builder, and then create a user interface service consumer model, using the Service Consumer and Data Services UI builder.

Parent topic: Tutorials for IBM WebSphere Portlet Factory: wpf7