Tutorial – Creating data-driven portlets

Overview

This tutorial relies on IBM® WebSphere® Portlet Factory Service-Oriented Architecture (SOA) in which one model provides the data services and a second application model consumes these services. The SOA architecture supports a concept called Service Provider stubs which function like real data providers but serves up static, sample data. Stubs allow developers to build applications and test them without having any real live database connections.

You will also be introduced to page automation builders. These builders are high-level builders that take in XML result sets and produce pages automatically to display the data properly even when the data or the data's schema change. By applying modifier builders and resource bundles, rich user interfaces (UIs) for these automated pages are easy to create and modify. Finally, you will make a portlet out of the application to see these high-level builders in action within the portal framework.

In this tutorial, you will:

• Create an application using low-level and high-level builders to display rows of data and single pages of data. The most significant high-level builder you will use is called Data Page. A Data Page builder can be given XML result sets generated from calls to the service provider for display. Using the data's schema and by examining the result set, Data Page can guess whether the data represents many records or a single record. Data Page automatically adapts itself to display rows of data, single pages of data, or data entry pages even when the schema of the data changes.
• Use WebSphere Portlet Factory's Service-Oriented Architecture. Data for the application comes from Service Provider models. The application retrieves that data from the provider via a Service Consumer builder. When multiple providers are built with the same interface, they can be used interchangeably. In turn, high-level, page automation builders adapt to the changes in the data's schema and produce a new version of the application to display the new data. For example, you will build an application to display employee data. Then you will switch service providers to one that provides data about product orders. By simply changing service providers, the employees application becomes a product orders application.
• Apply page formatting. Using modifier builders and resource bundles, you will apply formatting, column sorting, custom column labels, column hiding, and input page UI controls. These formatting controls are easy to apply, modify, and profile.
• Use Action List builders to control application function and flow. Action List builders contain a series of tasks that are performed when the list is invoked. This type of builder can accepts input arguments which it can use in performing its tasks. For example, an action list could accept an argument, use that argument as an input to invoke a service call, then open a page that displays the results of that service call.
• Incorporate reusable components. A model can be designed as a reusable component. If the model can run as an independent application, it can be imported into another model with a single builder call: Imported Model. By importing a model into a host model, the features of the imported model become part of the features of the host model. For example, you will be given a model that creates new employee records. By importing this model into the application you will build in this tutorial, the create employee features will be available in your application.
• Create a portlet. As in a previous tutorial, you will add and configure a Portlet Adapter builder call in the application so that it will function as a portlet.
• Become familiar with View & Form builders. View & Form is a key, higher order builder that includes many of the common features found in CRUD applications.

Setup Requirements

The following setup is required to run the tutorial.

• You need access to a local or networked installation of IBM WebSphere Portal and that WebSphere Portal server is running. The instructions in this tutorial assume that you have the WebSphere Portal server installed locally, though other configurations are possible, as described below.
• WebSphere Portlet Factory Designer must be installed locally. WebSphere Portlet Factory Designer is the development environment for creating web applications and portlets.
• A test application server environment must be available. Eclipse and the Embedded Test Environment for Rational Application Developer are standard test environments. You must know which server or test environment you intend to use.
• WebSphere Portlet Factory server must be running.

Create the Application Model

First build a new Web Application project called "MyFirstProject". The project must include the Tutorials and Samples feature set.


1. Add a new model to the Web App project

1. Right-click the project name and choose New > WebSphere Portlet Factory Model. This command will invoke a wizard to assist you in creating a new model.
2. Choose the project in which this model should be created. Your project name should be selected. Click Next to continue.
3. When creating a new model, you can choose from a list of starter models. In the Select Model panel, choose Main and Page from the Factory Starter Models category and click Next.
4. 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.
5. Every model needs to be stored 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\solutions\basics.
6. Every model must also have a file name. In the Model name field, enter EmployeesPortlet and click Finish. WebSphere Portlet Factory Designer will now create your new model and open it for you.
7. Run the model by clicking the right arrow icon from the row of icons immediately below the menu at the top of the workspace. A web browser will launch and will display this simple application containing a simple page.
8. Every model must also have a file name. In the Model name field, enter EmployeesPortlet and click Finish. WebSphere Portlet Factory Designer will now create your new model and open it for you.

2. Rename the Page Builder call and test

1. Edit the Page Builder named page1. Change its name to allEmployeesPage and click OK.
   Note: You should now see an error in the Problems tab at the bottom of the workspace. This error states that The Action "page1" was not found in "main". You will fix this minor problem in a moment.
2. Open the Action List builder call. In the Actions input, click the ellipsis icon on the row that contains page1.
3. Choose Pages > allEmployeesPage. Click OK to continue.
4. Click OK in the Action List builder call to save the changes. The error message about page1 not being found should have gone away.
5. Run the model again by clicking right arrow icon. The web page should look the same as it did the last time you tested it.

3. Get data from a service provider model via a Service Consumer builder.

4. Display the data on a page using a high-level builder called Data Page.


5. Demonstrate Basic Page Automation.

6. Apply Page Formatting.

Add Get Employee Features

1. Add a Page builder call

1. Click the builder picker icon to add a new builder call to the model.
2. Choose Page and click OK.
3. Name the page getEmployeePage.
4. Modify the contents of this page:
1. Add the following
   tag just before the closing tag:

   .
2. Click OK when finished.

2. Add an Action List builder
3. Add a Data Page to display the details of a single employee record.

1. 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.
   
   

Input Name	Enter this value for the given input
Name	getEmployeeDataPage
Variable	Click ellipsis icon and choose DataServices/EmployeeData/getRecord/results
Page in Model	getEmployeePage
Page Type	Infer from HTML
Make UI from Data	Check the box – It is checked by default but this input is important. It is the one that causes Data Page to examine the data and make decisions about how to present the data.
Location for New Tags	namedTag
Localized Resource	allEmployeesDataPageTranslate – This value declares that this Data Page will use the same resource bundle for field labels used by the allEmployeesDataPage builder call.

4. Add a Data Field Modifier to create a link out of the ID column.

1. Click builder picker icon to add a new builder call to the model.
2. Choose Data Field Modifier and click OK.
3. 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.
   
   

Input Name	Enter this value for the given input
Name	Select by Name
Field Selector Tool	Click ellipsis icon and choose [allEmployeesPage]allEmployeesDataPage/RowSet/Row/EMPNO.
Fields	getEmployeePage
Field Behavior	Action Field
Control Type	Link
Action Type	Link to an Action
Action	Click ellipsis icon and choose getEmployeeActions from the Methods folder.
Argument Name for Data	EmployeeID

4. Run the model to test your work by clicking right arrow icon. You should see a link in every row in the ID column.
5. Click a link to see what happens.
   Note: If you are using a Service Provider stub for the data, every link will open with the same sample data. If you are using a live Service Provider, each link will open the corresponding data record. In either case, notice that the EmployeeID number is passed on the URL. That is, http://.../Action!_gen_call_getEmployeeActions?EmployeeID=0002000.
6. Switch back to WebSphere Portlet Factory Designer when you are finished testing your application.

5. Add a Cancel button to allow the user to go back to the allEmployeesPage.

1. Click builder picker icon to add a new builder call to the model.
2. Choose Button and click OK.
3. 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.
   
   

Input Name	Enter this value for the given input
Name	getEmployeeCancel
Page	getEmployeePage
Tag	cancelButton
Label	Cancel. If the label for this button were stored in a variable or came from the results of a service call, you could choose the appropriate source. In this case, a simple text string will suffice.
Action Type	Link to an Action
Action	Click ellipsis icon and choose allEmployeesPage from the Pages folder.

4. Test the model by clicking right arrow icon . Open any employee's detail record by clicking on a link in the ID column. Use the Cancel button to see if it takes you back to the page with all of the employee data.

Using Imported Models

Building reusable components is an important goal in many application development environments. WebSphere Portlet Factory is no different. Most of the reusable components in WebSphere Portlet Factory are builders. However, models can be reused as well. One model with all of its features and capabilities can be included in many other application models by simply importing that model via an Imported Model builder.

The models being imported may already have some of its builder inputs profiled. If so, these inputs are exposed in the Imported Model builder. These exposed inputs allow the imported model to be configured at import time to work with the host model into which it is imported.

In this section, you will examine a model that creates new employee records, and then you will import that model into the EmployeesPortlet model. After importing this model, the employees portlet will have the ability to create new employees records.

1. Examine the Employees_Create model in models/tutorials/basics.

1. Open this model in WebSphere Portlet Factory Designer. Open the builders in the builder call list to see if you can understand what this model does.
2. Test the model. It should open a page containing a Create button.
3. Click the Create button. You should see a data input page for inputting an employee record.

2. Test this model with a different data schema.

1. Switch back to WebSphere Portlet Factory Designer.
2. Open the Service Consumer builder call named EmployeeData.
1. In the Provider Model field, click ellipsis icon and choose tutorials/basics/data/TutorialBasics_Provider_Orders_Stub.
2. Click OK to close this builder call.
3. Test the model in a browser again. This time, the model should present an input page for entering a product order.
4. Open the Service Consumer builder call named EmployeeData to return the service provider to its previous value.
1. In the Provider Model field, click ellipsis icon and choose tutorials/basics/data/TutorialBasics_Provider_Employees_Stub.
2. Click OK to close this builder call.
5. Test the model again. It should now present an input page for employee data.
6. Open the Employees_Create model.

4. Open the allEmployeesPage builder.

5. Copy the HTML from the Page Contents field.

6. Paste this text over the text in the corresponding field in the EmployeesPortlet model.

7. Import the Employees_Create model into the EmployeesPortlet model.

1. Open the EmployeesPortlet and click builder picker icon to add a new builder call to the model.
2. Choose Imported Model and click OK.
3. 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.
   
   

Input Name	Enter this value for the given input
Name	createEmployeeModel
Model	Click ellipsis icon and choose tutorials/basics/Employees_Create.
Profile Handling	Set individual inputs.
Include main Action List?	Deselect this option.
Include allEmployees Page?	Deselect this option.
Include Service Consumer?	Deselect this option.

4. Test the model again. This time there should be a Create button.

1. Click the Create button to see what happens. You should see an input form for creating an employee.
2. Click the Submit button without supplying any values. The fields with the red stars are required and should fail validation.
3. Provide inputs for the required fields and submit. You should see the starting page of the application with rows of employee data.
   Note: If using a Service Provider stub for data, the new record will not be added to the stub data.
4. Switch back to WebSphere Portlet Factory Designer.

Apply Formatting to an Input Form

Earlier in this tutorial, you applied page formatting using a resource bundle and some modifier builders. In this section, you will apply formatting to a data entry form. Since data entry forms contain HTML fields, there are special builders designed to modify how Data Page renders those input fields.

For example, Data Page might present a plain text field to enter data such as one's work department. A better UI choice might be a drop-down list of department names. A Rich Data Definition builder call that refers to an XML file with UI details can easily format many input fields on a page.

Once the fields are automatically placed on the page, changing their order or grouping them together might improve the UI of the page. A Data Hierarchy Modifier builder call is used to perform this task. In this builder call, you can use "drag and drop" to change the order of the fields on the page and set the "begin" and "end" points of groups of inputs.

These concepts are easier to understand by using them in a model. The following steps will help you to understand the XML file referred to by the Rich Data Definition builder call and the grouping of inputs via a Data Hierarchy modifier.

1. Examine a Rich Data Definition file.

1. Starting from the root of the project, open the following file: MyFirstProject/WebContent/samples/tutorials/data_definitions/tutorial_basics_richUI.xml.
2. At the top of this file, there are definitions called base_TextInput, base_DateInput, and base_RadioButton. These definitions declare default values for various data entry User Interface (UI) elements. Other definitions within this file can refer to these named definitions as their base UI element type. The default values can be overridden providing alternative values in subsequent data definitions.
3. Scroll down this file and find the XML node that looks like this: . This data definition contains details about how the fields for a single set of data input fields should behave.
1. Look at the node of this data definition for details about the input fields. FIRSTNME, LASTNAME, MIDINIT,and WORKDEPT for example, are all text input fields but they have different attributes. Some are required and some have controls for their HTML attributes such as size and maxlength.
2. Notice that the base type of these fields is called base_TextInput. Scroll up to the definition of base_TextInput to see the default values and UI element type for these fields.
4. Scroll further down this file to find the elements using the base_DateInput UI element. These two fields will have a Calendar Picker UI element to assist users in entering dates.
5. Locate the data definitions for the fields called JOB and EDLEVEL. These definitions have a list of . These values will appear as a list of values from which the user can choose.
6. Close this file when you are finished examining it.

2. Add a Rich Data Definition Builder call.

1. Click builder picker icon to add a new builder call to the model.
2. Choose Rich Data Definition and click OK.
3. 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.
   

Input Name	Enter this value for the given input
Schema	EmployeeDataOneRecordTransformSchema
Data Definition Type	Read Data Definition File
Data Definition File	Click ellipsis icon and choose /samples/tutorials/data_definitions/tutorial_basics_richUI.xml

4. Test the model again. This time there should be a better UI for the input fields.

3. Add a Data Hierarchy Modifier builder call.

1. Click builder picker icon to add a new builder call to the model.
2. Choose Data Hierarchy Modifier and click OK.
3. Use the following table for the details about what values to provide for the various inputs to this builder call.
   
   

Input Name	Enter this value for the given input
Name	createEmployeeFormatting
Field Selector Tool	Select by Name
Fields	Click ellipsis icon and choose [createEmployeePage]createEmployeeDataPage/Row.
New Group Names	Personal, Business, Other – Click Apply after adding these group names to refresh the table below this field.

4. Group the inputs. Use the mouse to drag and drop fields in between the start and end rows for each group.
   
   Group the inputs as follows:
   
   

Group Name	Fields that belong in the Group
Personal	FIRSTNME, MIDINIT, LASTNAME
Business	WORKDEPT, PHONENO, HIREDATE, JOB
Other	EDLEVEL, SEX, BIRTHDATE, SALARY, BONUS, COMM

5. Click OK when you have finished.
6. Test the model again. This time the input page should show groups of inputs.
   

Turning the Application into a Portlet

In this section, you will create a model and then add it a Portlet Adapter builder call to enable the application to function within the WebSphere Portal framework.

1. Add a Portlet Adapter builder to the model.

1. Click builder picker icon to add a new builder call to the model.
2. Choose the Portlet Adapter builder and click OK.
3. 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.

Input Name	Enter this value for the given input
Name	Tutorial Basics Employees
Portlet Title	Tutorial Basics – Employees Portlet
Portlet Description	Tutorial Basics – Portlet for Employee Information

4. Click OK when you have finished.
5. Click OK and save the model.
6. 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

2. Open the Basics page and add EmployeesPortlet

1. Log into WebSphere Portal as an administrator.
2. Click the Administration link.
3. Under Portal User Interface click Manage Pages.
4. Find the link to the Content Root page and click it.
5. Find the link to the My Work page and click it.
6. Find the link to the Portlet Factory page and click it.
7. Find the link to the Tutorials page and click it.
8. Find the link to the Basics page and click it.
9. Click Open Portlet palette to open the Portlet palette.
10. Use the search feature to find your portlet in the list.
11. Click on the portlet and continue to hold the mouse key down.
12. Drag the portlet to a destination on the page. A horizontal bar appears as you drag the portlet over areas on the page available for publishing. When you drag the portlet within close proximity of a permissible drop zone, the color of the horizontal bar changes from a muted to a more saturated tone.
13. Drop the portlet to the page as appropriate by releasing the mouse key to add the portlet where you view a horizontal bar.
14. Click Close Portlet Palette to close the Portlet Palette.

Using Higher Order Builders

Many tasks you just learned are encapsulated in higher order builders. In order to understand these builders, it is best to learn to work with lower order builders first. This tutorial has shown you how to perform some of these tasks already.

View & Form is a higher order page automation builder. It encapsulates many other builders' functions into a simple user interface. Adding paging buttons, enabling the ability to update and display records, and generating its own main method makes View & Form a very convenient starting point for creating a data-driven application.

A common pattern for data-driven applications is to use SOA for the data integration and View & Form for the display and editing of the data. Features of the View & Form-based application can be changed by using modifier builders. Data Column Modifier, Data Hierarchy Modifier, and Rich Data Definition are a few of the most common modifier builders used with View & Form.

There is another solution model called EP_View_and_Form. This model performs more functions and has a richer UI using only a handful of builder calls. Open this model and run it. Study the contents of the View & Form builder call. As you move forward in building models and gaining more experience, you should learn to use View & Form and the common modifier builders.
Summary

Now that you have completed this tutorial, you should understand the following concepts:

• The Service-Oriented Architecture separates data provider models from data consumer models. The providers have services that can be invoked by consumers to get the data needed by the consumers. Consumer models use this data for display and other related functions.
• Data Page can be used to display rows of data, single records, and to create input pages. Page automation builders such as Data Page adapt themselves to changes in data and schema to allow a single application model to be reused for different data sets.
• When using page automation builders, details about formatting and UI controls are handled by resource bundles and modifier builders.
• Models can be imported into other models to add the first model's features to the second model. Importing models is an easy and effective way to use models as reusable components.