Introduction to Web Experience Factory

Chelis Camargo

September 2012

What is Web Experience Factory?

Web Experience Factory is a rapid application development tool, which applies software automation technology to construct applications. By using WEF, developers can quickly create single applications that can be deployed to a variety of platforms, such as IBM WebSphere Application Server and IBM WebSphere Portal Server , which in turn can serve your application to standard browsers, mobile phones, tablets, and so on.

Web Experience Factory is the new product derived from the former WebSphere Portlet Factory (WPF) product. In addition to creating portal applications, WEF always had the capability of creating exceptional web applications. In fact, the initial product developed by Bowstreet, the company which originally created WPF, was meant to create web applications, way before the dawn of portal technologies. As the software automation technology developed by Bowstreet could easily be adapted to produce portal applications, it was then tailored for the portal market. This same adaptability is now expanded to enable WEF to target different platforms and multiple devices.

Key benefits of using Web Experience Factory for portlet development

While WEF has the capability of targeting several platforms, we will be focusing on IBM WebSphere Portal applications.

The following are a few benefits of WEF for the portal space:

  • Significantly improves productivity
  • Makes portal application development easier
  • Contains numerous components (builders) to facilitate portal application development
  • Insulates the developer from the complexity of the low-level development tasks
  • Automatically handles the deployment and redeployment of the portal project (WAR file ) to the portal
  • Reduces portal development costs

The development environment

Before we discuss key components of WEF, let's take a look at the development environment.

From a development environment perspective, WEF is a plugin that is installed into either Eclipse or IBM Rational Application Developer for WebSphere. As a plugin, it uses all the standard features from these development environments at the same time that it provides its own perspective and views to enable the development of portlets with WEF.

Let's explore the WEF development perspective in Eclipse. The WEF development environment is commonly referred to as the designer. While we explore this perspective, you will read about new WEF-specific terms. In this section, we will neither define nor discuss them, but don't worry. Later on in this article, you will learn all about these new WEF terms.

The following screenshot shows the WEF perspective with its various views and panes:

The top-left pane, identified by number 1, shows the Project Explorer tab. In this pane you can navigate to the WEF project, which has a structure similar to a JEE project. WEF adds a few extra folders to host the WEF-specific files. Box 1 also contains a tab to access the Package Explorer view. The Package Explorer view enables you to navigate the several directories containing the .jar files. These views can be arranged in different ways within this Eclipse perspective.

The area identified by number 2 shows the Outline view. This view holds the builder call list. This view also holds two important icons. The first one is the "Regeneration" button. This is the first icon from left to right, immediately above the builder call table header. Honestly, we do not know what the graphical image of this icon is supposed to convey. Some people say it looks like a candlelight, others say it looks like a chess pawn. We even heard people referring to this icon as the "Fisher-Price" icon, because it looks like the Fisher-Price children's toy.

The button right next to the Regeneration button is the button to access the Builder palette. From the Builder palette, you can select all builders available in WEF.

Box number 3 presents the panes available to work on several areas of the designer. The screenshot inside this box shows the Builder Call Editor. This is the area where you will be working with the builders you add to your model.

Lastly, box number 4 displays the Applied Profiles view. This view displays content only when the open model contains profile-enabled inputs, which is not the case in this screenshot.

The following screenshot shows the right-hand side pane, which contains four tabs—Source, Design, Model XML, and Builder Call Editor.

The preceding screenshot shows the content displayed when you select the first tab from the right-hand side pane, the Source tab. The Source tab exposes two panes. The left-hand side pane contains the WebApp tree, and the right-hand side pane contains the source code for elements selected from the WebApp tree.

Although it is not our intention to define the WEF elements in this section, it is important to make an exception to explain to you what the WebApp tree is. The WebApp tree is a graphical representation of your application. This tree represents an abstract object identified as WebApp object. As you add builders to your models or modify them, these builders add or modify elements in this WebApp object. You cannot modify this object directly except through builders.

The preceding screenshot shows the source code for the selected element in the WebApp tree. The code shows what WEF has written and the code to be compiled.

The following screenshot shows the Design pane. The Design pane displays the user interface elements placed on a page either directly or as they are created by builders. It enables you to have a good sense of what you are building from a UI perspective.

The following screenshot shows the content of a model represented as an XML structure in the Model XML tab. The highlighted area in the right-hand side pane shows the XML representation of the sample_PG builder, which has been selected in the WebApp tree.

We will discuss the next tab, Builder Call Editor, when we address builders in the next section.

Key components of WEF—builders, models, and profiles

Builders, models, and profiles comprise the key components of WEF. These three components work together to enable software automation through WEF. Here, we will explain and discuss in details what they are and what they do.


Builders are at the core of WEF technology.

There have been many definitions for builders. Our favorite is the one that defines builders as "software components, which encapsulate design patterns".

Let's look at the paradigm of software development as it maps to software patterns. Ultimately, everything a developer does in terms of software development can be defined as patterns. There are well-known patterns, simple and complex patterns, well-documented patterns, and patterns that have never been documented. Even simple, tiny code snippets can be mapped to patterns.

Builders are the components that capture these countless patterns in a standard way, and present them to developers in an easy, common, and user-friendly interface. This way, developers can use and reuse these patterns to accomplish their tasks.

Builders enable developers to put together these encapsulated patterns in a meaningful fashion in such a way that they become full-fl edged applications, which address business needs. In this sense, developers can focus more on quickly and efficiently building the business solutions instead of focusing on low-level, complex, and time consuming development activities.

Through the builder technology, senior and experienced developers at the IBM labs can identify, capture, and code these countless patterns into reusable components. When you are using builders, you are using code that has not only been developed by a group, which has already put a lot of thought and effort into the development task, but also a component, which has been extensively tested by IBM. Here, we will refer to the IBM example, because they are the makers of WEF—but overall, any developer can create builders.

Simple and complex builders

The same way that development activities can range from very simple to very complex tasks, builders can also range from very simple to very complex.

Simple builders can perform tasks such as placing an attribute on a tag, highlighting a row of a table, or creating a simple link. Equally, there are complex builders , which perform complex and extensive tasks. These builders can save WEF developers' days worth of work, troubleshooting, and aggravation. For instance, there are builders for accessing, retrieving, and transforming data from backend systems, builders to create tables, form, and hundreds of others.

The face of builders

The following screenshot shows a Button builder in the Builder Editor pane:

All builders have a common interface, which enables developers to provide builder input values. The builder input values define several aspects concerning how the application code will be generated by this builder. Through the Builder Editor pane, developers define how a builder will contribute to the process of creating your application, be it a portlet, a web application, or a widget.

Any builder contains required and optional builder inputs. The required inputs are identified with an asterisk symbol (*) in front of their names. For instance, the preceding screenshot representing the Button builder shows two required inputs—Page and Tag.

As you can see through the preceding screenshot, builder input values can be provided through several ways. The following table describes the items identified by the numbered labels:

Label number




Free form inputs

Enables developer to type in any appropriate value.


Drop-down controls

Enables developer to select values from a predefined list, which is populated based on the context of the input.

This type of input is dynamically populated with possible influence from other builder inputs, other builders in the same model, or even other aspects of the current WEF project.


Picker controls

This type of control enables users make a selection from multiple source types such as variables, action list builders, methods defined in the current model, public methods defined in java classes and exposed through the Linked Java Class builder, and so on. The values selected through the picker controls can be evaluated at runtime.


Profiling assignment button

This button enables developers to profile-enable the value for this input. In another words, through this button, developers indicate that the value for this input will come from a profile to be evaluated at regeneration time.



Through these controls, builders contribute to make the modeling process faster at the same time it reduces errors, because only valid options and within the proper context are presented.

Builders are also adaptive. Inputs, controls, and builder sections are either presented, hidden, or modified depending upon the resulting context that is being automatically built by the builder. This capability not only guides the developers to make the right choices, but it also helps developers become more productive.

Builder artifacts

We have already mentioned that builders either add artifacts to or modify existing artifacts in the WebApp abstract object. In this section, we will show you an instance of these actions. In order to demonstrate this, we will not walk you through a sample. Rather, we will show you this process through a few screenshots from a model.

Here, we will simulate the action of adding a button to a portlet page.

In WEF, it is common to start portlet development with a plain HTML page, which contains mostly placeholder tags. These placeholders, usually represented by the names of span or div tags, indicate locations where code will be added by the properly selected builders. The expression "code will be added" can be quite encompassing. Builders can create simple HTML code, JavaScript code, stylesheet values, XML schemas, Java code, and so on. In this case, we mean to say that builders have the capability of creating any code required to carry on the task or tasks for which they have been designed.

In our example, we will start with a plain and simple HTML page, which is added to a model either through a Page builder or an Imported Page builder.

Our sample page contains the following HTML content:

Now, let's use a Button builder to add a button artifact to this sample_PG page, more specifically to the sampleButton span tag. Assume that this button performs some action through a Method builder (Java Method), which in turn returns the same page.

The following screenshot shows what the builder will look like after we provide all the inputs we will describe ahead:

Let's discuss the builder inputs we have provided in the preceding screenshot. The first input we provide to this builder is the builder name. Although this input is not required, you should always name your builders. Some naming convention should be used for naming your builders. If you do not name your builders, WEF will name them for you.

The following table shows same sample names, which adds an underscore followed by two or three letters to indentify the builder type:

Builder type

Builder name







Data Page




Imported Model


Model Container


There are several schools of thoughts regarding naming convention. Some scholars like to debate in favor of one or another. Regardless of the naming convention you adopt, you need to make sure that the same convention is followed by the entire development team.

The next inputs relate to the location where the content created by this builder will be placed. For User Interface builders, you need to specify which page will be targeted. You also need to specify, within that page, the tag with which this builder will be associated. Besides specifying a tag based on the name, you can also use the other location techniques to define this location.

In our simple example, we will be selecting the sample_PG page. If you were working on a sample, and if you would click on the drop-down control, you would see that only the available pages would be displayed as options from which you could choose. When a page is not selected, the tag input does not display any value. That is because the builders know how to present only valid options based on the inputs you have previously provided.

For this example, we will select sample_PG for page input. After doing so, the Tag input is populated with all the HTML tags available on this page. We selected the sampleButton tag. This means that the content to be created on this page will be placed at the same location where this tag currently exists. It replaces the span tag type, but it preserves the other attributes, which make sense for the builder being currently added.

Another input is the label value to be displayed. Once again, here you can type in a value, you can select a value from the picker, or you can specify a value to be provided by a profile. In this sample, we have typed in Sample Button.

For the Button builder, you need to define the action to be performed when the button is clicked. Here also, the builder presents only the valid actions from which we can select one. We have selected, Link to an action.

For the Action input, we select sample_MTD. This is the mentioned method, which performs some action and returns the same page.

Now that the input values to this Button builder have been provided, we will inspect the content created by this builder.

Inspecting content created by builders

The builder call list has a small gray arrow icon in front of each builder type. By clicking on this icon, you cause the designer to show the content and artifacts created by the selected builder:

By clicking on the highlighted link, the designer displays the WebApp tree in its right-hand side pane. By expanding the Pages node, you can see that one of the nodes is sample_BTN, which is our button. By clicking on this element, the Source pane displays the sample page with which we started. If necessary, click on the Source tab at the bottom of the page to expose the source pane.

Once the WebApp tree is shown, by clicking on the sample_BTN element, the right-hand side pane highlights the content created by the Button builder we have added.

Let's compare the code shown in the preceding screenshot against the original code shown by the screenshot depicturing the Sample Page builder. Please refer to the screenshot that shows a Sample Page builder named sample_PG. This screenshot shows that the sample_PG builder contains simple HTML tags defined in the Page Contents (HTML) input. By comparing these two screenshots, the first difference we notice is that after adding the Button builder, our initial simple HTML page became a JSP page, as denoted by the numerous JSP notations on this page.

We can also notice that the initial sampleButton span tag has been replaced by an input tag of the button type. This tag includes an onClick JavaScript event. The code for this JavaScript event is provided by JSP scriptlet created by the Button builder.

As we learned in this section, builders add diverse content to the WebApp abstract object. They can add artifacts such as JSP pages, JavaScript code, Java classes, and so on, or they can modify content already created by other builders. In summary, builders add or modify any content or artifacts in order to carry on their purpose according to the design pattern they represent.


Another important element of WEF is the Model component. Model is a container for builder calls. The builder call list is maintained in an XML file with a .model extension. The builder call list represents the list of builders added to a model.

The Outline view of the WEF perspective displays the list of builders that have been added to a model.

The following screenshot displays the list of builder calls contained in a sample model:

To see what a builder call looks like inside the model, you can click on the gray arrow icon in front of the builder type and inspect it in the Model XML tab.

For instance, let's look at the Button builder call inside the sample model we described in the previous section.

The preceding image represents a builder call the way it is stored in the model file. This builder call is one of the XML elements found in the BuilderCallList node, which in turn is child of the Model node. Extra information is also added at the end of this file.

This XML model file contains the input names and the values for each builder you have added to this model. WEF operates on this information and the set of instructions contained in these XML elements, to build your application by invoking a process known as generation or regeneration to actually build the executable version of your application, be it a portlet, a web application, or a widget. We will discuss more on regeneration at the end of this article.

It is important to notice that models contain only the builder call list, not the builders themselves. Although the terms—builder call and builder are used interchangeably most of the times, technically they are different. Builder call can be defined as an entry in your model, which identifies the builder by the Builder call ID, and then provides inputs to that builder. Builders are the elements or components that actually perform the tasks of interacting with the WebApp object. These elements are the builder definition file (an XML file) and a Java Class. A builder can optionally have a coordinator class. This class coordinates the behavior of the builder interface you interact with through the Builder Editor.


Unlike traditional development process utilizing pure Java, JSP, JavaScript coding, WEF enables developers to model their application. By modeling, WEF users actually define the instructions of how the tool will build the final intended application. The time-consuming, complex, and tedious coding and testing tasks have already been done by the creators of the builders. It is now left to the WEF developer to select the right builders and provide the right inputs to these builders in order to build the application.

In this sense, WEF developers are actually modelers. A modeler works with a certain level of abstraction by not writing or interacting directly with the executable code. This is not to say that WEF developers do not have to understand or write some Java or eventually JavaScript code. It means that, when some code writing is necessary, the amount and complexity of this code is reduced as WEF does the bulk of the coding for you.

There are many advantages to the modeling approach. Besides the fact that it significantly speeds the development process, it also manages changes to the underlying code, without requiring you to deal with low-level coding. You only change the instructions that generate your application. WEF handles all the intricacies and dependencies for you.

In the software development lifecycle, requests to change requirements and functionality after implementation are very common. It is given that your application will change after you have coded it. So, be proactive by utilizing a tool, which efficiently and expeditiously handles these changes. WEF has been built with the right mechanism to graciously handle change request scenarios. That is because changing the instructions to build the code is much faster and easier than changing the code itself.

Code generation versus software automation

While software has been vastly utilized to automate an infinite number of processes in countless domains, very little has been done to facilitate and improve software automation itself. Prior to being a tool for building portlets, WEF exploits the quite dormant paradigm of software automation.

It is beyond the scope of this book to discuss software automation in details, but it is suffice to say that builders, profiles, and the regeneration engine enable the automation of the process of creating software. In the particular case of WEF, the automation process targets web applications and portlets, but it keeps on expanding to other domains, such as widgets and mobile phones.

WEF is not a code generation tool. While code generation tools utilize a static process mostly based on templates, WEF implements software automation to achieve not only high productivity but also variability.


In the development world, the word profile can signify many things. From the WEF perspective, profile represents a means to provide variability to an application. WEF also enables profiles or profile entries to be exposed to external users. In this way, external users can modify predefined aspects of the application without assistance from development or redeployment of the application.

The externalized elements are the builder input values. By externalizing the builder input values, line of business, administrators, and even users can change these values causing WEF to serve a new flavor of their application.

Profile names, profile entry names, which map to the builder inputs, and their respective values are initially stored in an XML file with a .pset extention . This is part of your project and is deployed with your project. Once it is deployed, it can be stored in other persistence mechanisms, for example a database.

WEF provides an interface to enable developers to create profile, define entries and their initial values, as well as define the mechanism that will select which profile to use at runtime. By selecting a profile, all the entry values associated with that profile will be applied to your application, providing an unlimited level of variability.

Variability can be driven by personalization, configuration, LDAP attributes, roles, or it can even be explicitly set through the Java methods.

The following screenshot shows the Manage Profile tab of Profile Manager. The Profile Manager enables you to manage every aspect related to profile sets. The top portion of this screenshot lists the three profiles available in this profile set. The bottom part of this screenshot shows the profile entries and their respective values for the selected profile:

Regeneration engine

Now that you have learned about builders, models, and profiling, we can discuss the component that uses these elements to create your application, the regeneration engine.

We believe that, besides builders with its profiling capability, regeneration process is what sets WEF apart from any other rapid application development tool or code generators for this matter.

Sometimes, regeneration engine is also called generation engine. This is a small detail, but generation happens only the first time when your application is constructed by WEF. Regeneration takes place every time after that. So, one should think that it makes more sense to call this process regeneration instead of generation. Hence, we refer to it in this book as regeneration engine.

The regeneration process is the process by which the component of WEF known as regeneration engine constructs the representation of you application. In order to perform this task, the regeneration engine goes through the list of all builder calls in the model; looks at their input values that might be coming from the several sources we have provided, including a profile and their relationships; and then constructs the WebApp abstract object. The regeneration engine is responsible for making the call to the actual builders, in the proper order, passing in the right and the latest input values for those builders.

The following diagram demonstrates the regeneration process where models and profiles are used to generate instances of WebApps:

As we have already seen, builders can reference actions or artifacts created by other builders or even external components. The regeneration engine has the intelligence and the ability to understand and interpret these relationships and build a representation of all these complexities. As builders are added or removed from the model, their inputs and relationships change and the regeneration engine re-executes to make sure that the representation of your application maintains its functionality and integrity.

Regeneration happens both at design time as well as at runtime.

Creating a WEF project

If you do not have access to an instance of Web Experiece Factory, you can download an evaluation copy from IBM site. The following is the link: developerworks/downloads/ws/wpf/.

This trial version is valid for a period of 60 days. Please notice that the current version available for download is Version 8. In this book, we have covered Version 7.0, because Version 8 was not available at the time we started writing this book.

In order to create your portlets, first you need to create your WEF project either in Eclipse or in Rational Application Developer (RAD) . The process is the same whether in Eclipse or RAD. As we are using Eclipse, let's walk though the process of creating a WEF project in Eclipse.

Before you start your project, you should have your IBM WebSphere Portal Server up and running. We will instruct WEF to deploy the portlets we created in this project directly to the portal server. Perform the following steps:

  1. Open your Eclipse. By default, it should open on the WEF perspective. The currently open perspective is indicated in the top-right side. If the WEF perspective is not currently open, then from the top menu, select Window | Open Perspective | Other | WebSphere Portlet Factory.
  2. From the top menu, select File | New | WebSphere Portlet Factory. The Create WebSphere Portlet Factory Project window will open.
  3. For Project name type A2Z. Leave Use default location checked and uncheck Create default folders.
    The following screenshot shows the first screen for creating your project:
  4. Click on Next. The next window, entitled—Feature Set page, enables you to select feature sets you would like to add to this project. By default, Dojo Extension – 1.x is checked. Leave it checked and click on Next.
  5. The next window, entitled—Server Configuration, enables you to define a server configuration. If you do not have one for your portal, let's create one:
    • Click on the Create Server Configuration... button. The Create Server Configuration window is displayed. This window contains a list of supported servers.
    • We will be using Portal Server 7.0. So, you should select IBM WebSphere Application Server and Portal Server 7.x. Click on OK. The Edit Server Configuration window is displayed where you can provide information about your server.
    • The following screenshot shows the Edit Server Configuration window, which is presented once you select the type of server for which you want to create a configuration.
    • WEF ships with a version of WebSphere Application Server Community Edition Server (WAS CE). WAS CE is installed by default when you install WEF. If you do not want to install WAS CE, then you need to perform a custom install and disable the installation of WAS CE. If you run the default install, then you also have the opportunity to deploy your projects to WAS CE.

    • You can test the SOAP connector port, by clicking on the Detect button.
    • Port numbers are assigned when the portal server is installed, and they may vary from system to system. For Windows systems, during installation Portal Install scans for available ports starting at port number 10000.

    • For Portlet API, select Java Portlet Standard 2.0. This equates to JSR 286 standards.
    • Provide the portal credentials and perform a test to make sure that both the SOAP port number and the credentials are correct.
    • For the Create Test Portal Page option, select Single Page. This is a nifty option available on WEF 7.x, which creates a portal page in the portal. When you create your portlet, it then automatically places your portlet on that page. This page will have the same name as your current project.
    • Once you confirm the information you have provided is correct, click on the OK button.
  6. This will bring you back to the Server Configuration window. Click on OK in this window. A dialog box will inquire if you want to publish your project. Click on Yes.

WEF should display a message indicating that your project has been successfully published. Your WEF project contains all the artifacts required for you to develop your application. It also includes all the supporting fi les for any feature set you might have selected.

The steps you have completed in the preceding section will cause your project to be published to the installed servers.

The development WAR fi le will be published to the WebSphere Application Server. This WAR fi le is used for testing purpose, because it enables you to run your models from the designer. The portlet WAR fi le will be published to the WebSphere Portal Server.

Creating your first Portlet

Now that you have created your project, we will create your first model, which will also be a portlet. Perform the following steps for doing so:

  1. In the designer, make sure the Project Explorer tab is open in the top-left pane. Right-click your project, and select New | WebSphere Portlet Factory Model.
  2. Choose A2Z from the WebSphere Portlet Factory Model window, and click on Next. A new page is displayed.
  3. From this new page, you can select from a list of different starter models. Please select Simple "Hello World" Model.
    The following screenshot shows the Select Model window with Simple "Hello World" Model:
  4. Click on Next. In the Basic Information window, leave the Deploy this model as a portlet checkbox selected. Click on Next.
  5. In the next step, enter HelloWorld for Name* (No spaces). For Portlet Title, enter Hello World (with a space). Click on Next.
  6. On the display information page, for Entry Type select Just a line of text. For Text, enter Another Hello World!. Click on Next.
  7. In the Save New Model window, enter HelloWorld (no space). Yes, you had already provided the model name in a previous step, and now you have to provide the same information again. Well…Click on Finish.

You will see that WEF creates a new model with four builders for you. The first builder is the Portlet Adapter, which transforms your regular model into a JSR 286 portlet.

Executing your portlet from the designer

Now that you have a portlet, let's run this portlet from the designer. This is how you could quickly test your portlet.

By default, your designer should have a run configuration, which has been created by WEF. To run the current model, make sure that it is selected in the designer. Then click on the run icon. The run icon is the green circle with a white arrow inside pointing to right, as shown in the following screenshot:

Your default browser should be invoked, and the portlet you have just created should be displayed. This portlet should display the only page in your portlet with its Another Hello World! text.

When you run a model from the designer as instructed previously, you are running the project that has been deployed to the WAS instance upon which portal is running. In fact, your model is running as a web application. WEF refers to this action as running your model standalone. When your project is created, WEF adds several supporting fi les, which enables this project to be executed from your WAS server. These helping fi les are included only in the development WAR fi le. When you build your portlet WAR fi le, these fi les are excluded.

Deploying your portlet

Lastly, let's deploy your portlet to the portal and access it in the portal.

Your portlet WAR has already been deployed to portal. However, as you added a new portlet to your project, you need to publish your project again. This will cause the portlet.xml file to be rebuilt and include your newly created portlet.

Right-click on your A2Z project and select Publish Application... From the new window, make sure that the deployment configuration you have created is selected, then click on OK. It should take a minute or so to rebuild and redeploy your portlet WAR.

Now let's move to the portal side. WEF does a great job behind the scenes to make the task of testing your portlets in the portal much easier. As you recall, when you created you project, you have specified in one of the inputs that you wanted WEF to create a page for you in the portal. Now that you have created your portlet, WEF automatically places this portlet on that page for you. So, all you need to do to access your portlet is to log in to portal, and click on your page. Once you log in to your portal, you should see a page named A2Z. Click on this page. This page should contain your Hello World Portlet.

Congratulations! You have just built and accessed your first portlet built with WEF.

You've been reading an excerpt of:

IBM Websphere Portal 8: Web Experience Factory and the Cloud

Explore Title