About the Original Author

Recent articles by this author

Overview
The Web Experience Factory (WEF) 8.0 release contains an enhancement to the web service call builders that gives you an option to define a global JAXWS handler class. This handler makes it possible for models to intercept and process the inbound and outbound SOAP envelopes ...

A quick snapshot of what's new in IBM Web Experience Factory... IBM Web Experience Factory is all about making it quick and easy to develop applications (portlets) that are included as part of an exceptional web experience. We've seen our customers doing some awesome stuff, whether it be ...

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.

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

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.

Choose the project in which this model should be created. Your project name should be selected. Click Next to continue.

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.

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.

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.

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.

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.

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

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.

Open the Action List builder call. In the Actions input, click the ellipsis icon on the row that contains page1.

Choose Pages > allEmployeesPage. Click OK to continue.

Click OK in the Action List builder call to save the changes. The error message about page1 not being found should have gone away.

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.

A Service Consumer works in conjunction with the service definition and Service Operation builders, and is used to provide access to a public service created by those builders in a Service Provider model. The basic idea is that one model, the service provider, has exposed services that can retrieve data from a data source and return that data to a Service Consumer model. The Service Consumer builder is used to make these services available in an application model. The data returned by the Provider model is in an XML format that can be used easily by sophisticated builders like Data Page to render an HTML page containing the data.

In this tutorial, the Employees portlet needs Employee data. The Provider model has been supplied to you in the Tutorials and Samples feature set and provides the data needed by the Employees portlet. For convenience, the Provider model is a stub provider meaning that it does not connect to a real datasource. Instead, it has an interface that appears to the consumer model as if it is getting real data but is actually providing static data that was copied from a database during development of the Provider model.

Click builder picker icon to add a new builder call to the model.

Choose Service Consumer and click OK.

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.

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

The Data Page builder creates a structure based on the XML data in a variable and renders this structure as a form (both input and display) on a page. The structure created by the Data Page describes the data to be displayed as well as how to render the data on the form. A schema associated with the data on which the Data Page operates can determine how the data gets displayed as can the HTML page associated with the Data Page.

Use the Data Page builder to create forms that either display data, prompt the user to enter data, or are a combination of the two. Typically, Data Page is used to display the results of a service call or SQL statement or to create input forms based on an element type defined by a schema and an associated variable.

Click builder picker icon to add a new builder call to the model.

Choose Data Page and click OK.

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.

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

Choose namedTag.

5. Demonstrate Basic Page Automation.

In this step, you will be guided through changing the Service Provider model to one that provides different data unrelated to employees. You will see that Data Page is able to accept the new schema and the new data and render a page that shows orders data instead of employees data.

Switch back to WebSphere Portlet Factory Designer to make some changes to help you understand Data Page better. You will change the Data Provider model from an employees data service to a product orders data service. Soon you will see that by consuming different data, Data Page adapts.

Open the Service Consumer builder call. In the Provider Model input, click ellipsis icon and choose tutorials/basics/data/TutorialBasics_Provider_Orders_Stub.

Test the model again. This time you should see rows of data about product orders instead of employees.

Open the Service Consumer builder call. In the Provider Model input, click ellipsis icon and choose tutorials/basics/data/TutorialBasics_Provider_Employees_Stub.

A resource bundle is basically a text file with name-value pairs that map the actual column names from the data retrieved from the Service Provider model to more readable names. For example, LAST_NAME could be mapped to Last Name to make it easier to read.

A modifier builder is added to a model after a high-level builder like Data Page to allow finer control over the work done by the high-level builder. For example, a Data Field modifier can be added to a model containing a Data Page builder in order to add a link on every row in a given column to perform a certain task when clicked. A Data Column modifier could be added to change the order of columns, hide certain columns, and include sorting features for other columns.

Open the Data Page builder call and expand the Label Translation Settings field.

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.

Use the following table to set the column attributes for the data display table. The objective is to hide several columns and create sorting links out of several column headers. Click OK when you are finished entering these values. Note: The columns may not be listed in the same order as what is shown here. To be consistent and to avoid confusion, you should use the mouse to drag and drop the columns to get them in the same order as the table below.

Column Name

Status

Column Sort Type

EMPNO

Do Not Change

Not Sortable

LASTNAME

Do Not Change

Case Insensitive String

FIRSTNME

Do Not Change

Case Insensitive String

MIDINIT

Hide

Not Sortable

PHONENO

Do Not Change

Not Sortable

WORKDEPT

Do Not Change

Case Insensitive String

JOB

Do Not Change

Not Sortable

HIREDATE

Do Not Change

Date

EDLEVEL

Hide

Not Sortable

SEX

Hide

Not Sortable

BIRTHDATE

Hide

Not Sortable

SALARY

Hide

Not Sortable

BONUS

Hide

Not Sortable

COMM

Hide

Not Sortable

Run the model again to test it. You should see links in the column headings that sort the table by the values in a given column. Click on a column heading to sort in ascending order. Click the column heading again to sort in descending order.

Add Get Employee Features

1. Add a Page builder call

Click the builder picker icon to add a new builder call to the model.

Choose Page and click OK.

Name the page getEmployeePage.

Modify the contents of this page:

Add the following

tag just before the closing tag:

.

Click OK when finished.

2. Add an Action List builder

An action list is much like a subroutine in concept. In the Actions field, there is a table that can contain a series of commands. Each time this action list is run, these tasks will be performed.

Action lists can have arguments. When the action list is invoked, the calling routine must provide the input argument values. These values can then be used in the action list's actions by indirect reference, for example: ${Arguments/EmployeeID}. In this tutorial, this action list has an argument the is used as the lookup key to retrieve the details of a given employee.

In the Name input, enter getEmployeeActions.

Expand the Arguments section of this builder call to declare an argument. The argument will be the unique identifier of a given row of data.

In the Name column, declare a new argument by typing in EmployeeID.

In the Data Type column on the same row, choose String from the list.

Collapse this section.

Add an Assignment command. An Assignment takes a value or expression and assigns it to a variable. You will take the action list's input argument and assign it to the input argument for the service that retrieves a single employee's information.

On the first row, click ellipsis icon and choose Special > Assignment. The Make Assignment dialog appears.

Click ellipsis icon in the Target field and choose DataServices > EmployeeData > getRecord > inputs > OneRecordInputs > Parameter1Value. Note: If you cannot choose anything past getRecord > inputs, click OK, and then manually append /OneRecordInputs/Parameter1Value. When using a Service Provider stub model, the details of the input schema may not be available in this chooser but are still required.

Click ellipsis icon in the Source field and choose Arguments > EmployeeID and then click OK.

Add the following actions to the list.

On the next row of the ActionList column, click ellipsis icon and choose DataServices > EmployeeData > getRecord and click OK. You should see this command get added to the list.

On the next row, click ellipsis icon and choose Pages > getEmployeePage and click OK. You should now see two commands in the list.

Click OK to close this builder call.

3. Add a Data Page to display the details of a single employee record.

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.

Click ellipsis icon and choose getEmployeeActions from the Methods folder.

Argument Name for Data

EmployeeID

Run the model to test your work by clicking right arrow icon. You should see a link in every row in the ID column.

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.

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.

Click builder picker icon to add a new builder call to the model.

Choose Button and click OK.

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.

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.

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.

Test the model. It should open a page containing a Create button.

Click the Create button. You should see a data input page for inputting an employee record.

Test the model again. It should now present an input page for employee data.

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.

Open the EmployeesPortlet and click builder picker icon to add a new builder call to the model.

Choose Imported Model and click OK.

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.

Click the Create button to see what happens. You should see an input form for creating an employee.

Click the Submit button without supplying any values. The fields with the red stars are required and should fail validation.

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.

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.

Starting from the root of the project, open the following file: MyFirstProject/WebContent/samples/tutorials/data_definitions/tutorial_basics_richUI.xml.

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.

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.

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.

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.

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.

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.

Close this file when you are finished examining it.

2. Add a Rich Data Definition Builder call.

Click builder picker icon to add a new builder call to the model.

Choose Rich Data Definition and click OK.

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.

Personal, Business, Other – Click Apply after adding these group names to refresh the table below this field.

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

Click OK when you have finished.

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.

Click builder picker icon to add a new builder call to the model.

Choose the Portlet Adapter builder and click OK.

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

Click OK when you have finished.

Click OK and save the model.

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 Web Application 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 the WebSphere Portlet Factory Designer also automatically publishes the new WAR replacing the old one.

Note: If you did not create a mapped drive to your Portal server and used the Automatic Sycronize option you will need to Publish your application before you run it in the designer.

2. Open the Basics page and add EmployeesPortlet

Log into WebSphere Portal as an administrator.

Click the Administration link.

Under Portal User Interface click Manage Pages.

Find the link to the Content Root page and click it.

Find the link to the My Work page and click it.

Find the link to the Portlet Factory page and click it.

Find the link to the Tutorials page and click it.

Find the link to the Basics page and click it.

Click Open Portlet palette to open the Portlet palette.

Use the search feature to find your portlet in the list.

Click on the portlet and continue to hold the mouse key down.

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.

Drop the portlet to the page as appropriate by releasing the mouse key to add the portlet where you view a horizontal bar.

Click Close Portlet Palette to close the Portlet Palette.

You should now see your portlet. It should:

Display rows of employee data.

Have a link on the ID for each row of data. Clicking the link should open a details page.Note: When using Service Provider stubs, the detail data should be the same sample data regardless of which link you click, but the URL should contain an argument called EmployeeID that equals the ID number you clicked on to bring up the details page.

Contain a Create button to create new employee records.Note: When using Service Provider stubs, the new records will not be added to the rows of data displayed on the first page of the portlet.

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.