IBM WebSphere Portlet Factory Overview - Lotus

Getting started with WebSphere Portlet Factory V6.1WebSphere Portlet Factory Development Team29 July 2008© Copyright International Business Machines Corporation 2008. All rights reserved.AbstractDiscover what the IBM® WebSphere® Portlet Factory can do for your portaldevelopment team. Learn key Portlet Factory concepts, and how to performprimary tasks, create data services, develop portlet user interfaces, techniquesfor debugging, and best practices for deployment. Put it all together to expediteand automate much of the production of the components in your portal interface.The 6.1 release of this guide includes information on the new features of the 6.1and 6.0.2 releases, such as REST service support and the new graphical Designview.

Table of contentsIBM WebSphere Portlet Factory overview......................................................................... 3Product overview ............................................................................................................ 3Technology overview...................................................................................................... 4Key concepts: builders, models, and profiles ............................................................. 5Using builders to create portlets or services ............................................................... 5Dynamic profiling....................................................................................................... 9Deployment overview................................................................................................... 10Creating a WebSphere Portlet Factory project ................................................................. 10Step 1: Install WebSphere Portlet Factory.................................................................... 10Step 2: Create a project that includes WebSphere Portlet Factory features. ................ 10Creating data services ....................................................................................................... 11Why use WebSphere Portlet Factory builders for SOA ............................................... 11Creating a service provider model ................................................................................ 12Step 1: Create a new, empty (service provider) model............................................. 12Step 2: Add a data integration builder to your model............................................... 12Step 3: Add a Service Definition builder to your model. ......................................... 13Step 4: Add one or more Service Operation builders to your model........................ 13Step 5: Test the model by running it......................................................................... 14Step 6: Add additional operations to your service.................................................... 14Step 7: Generate a stub model. ................................................................................. 14Additional features........................................................................................................ 14Developing the portlet user interface................................................................................ 15Creating a service consumer model .............................................................................. 15Creating the initial presentation interface..................................................................... 15View & Form builder................................................................................................ 15Alternative methods for creating the initial presentation.......................................... 16Adding builders to achieve the exact functionality you need....................................... 16Selecting builders for common tasks ................................................................................ 16Creating services........................................................................................................... 17Creating the initial portlet user interface ...................................................................... 18Working with tables, columns, and data layout............................................................ 21Working with variables and schemas ........................................................................... 22Controlling the validation, formatting, labels, and behavior of data fields .................. 23Using actions and events............................................................................................... 26Adding navigation and page actions............................................................................. 28Adding and controlling page elements ......................................................................... 30Using Ajax and related techniques ............................................................................... 32Integrating WebSphere Portal features ......................................................................... 34Sharing functionality or resources across models......................................................... 36Supporting translation and localized strings................................................................. 38Customizing the user interface and styles......................................................................... 38Supply your own style sheets or HTML layout pages.................................................. 38Modify or change the default HTML templates. .......................................................... 40Debugging Tips................................................................................................................. 40WebSphere Portlet Factory V6.0.1 Getting Started Guide - 2 -

Deployment....................................................................................................................... 41Resources .......................................................................................................................... 42IBM WebSphere Portlet Factory overviewThis section provides a high-level overview of the key features of WebSphere PortletFactory and the underlying technology. It then walks through an example of how to usethis product to create a portlet.Product overviewWebSphere Portlet Factory is a powerful and flexible tool for rapidly building portlets ontop of a service-oriented architecture. Developers are able to quickly and easily leveragetheir company's core assets, automatically assembling them into custom, high-valueportlets. Portlets created with WebSphere Portlet Factory are dynamic, robust Java 2Enterprise Edition (J2EE) applications that react automatically to change, and can befurther modified by business users in real time, to meet changing business requirementswithout requiring any coding, duplicating or versioning of assets. By eliminating the needto code all of these implementations and their variations, WebSphere Portlet Factorysimplifies the development, deployment, and change management process, savingcompanies time and money.The primary features of WebSphere Portlet Factory are as follows:• Multi-page custom portlets without coding. The WebSphere Portlet Factoryrapid application development (RAD) capabilities and ease of use enabledevelopers of all skill sets to create multi-page, complex portlets. Developersbuild portlets by defining a sequence of highly adaptive software componentscalled builders, which have an easy-to-use interface. Developers assemblebuilders into models, which then generate the application code. In this way,developers can capture and automate the process of building dynamic portlets,instead of explicitly coding each portlet.• Robust integration capabilities with enterprise applications and data.WebSphere Portlet Factory provides automatic integration with existingapplications and data including SAP, Lotus Domino, PeopleSoft, Siebel, WebServices, relational databases, and Excel. Developers can quickly createcomposite, high-value portlets that leverage existing investment in your existingapplications and data.• Automatic integration with WebSphere Portal. With WebSphere PortletFactory, you have direct integration with IBM WebSphere Portal features suchas portlet wiring, Click-to-Action, business user configuration, peopleawareness, WebSphere Portal groups, and the credential vault. Portlets aredeployed automatically to WebSphere Portal software.• Support for SOA development. WebSphere Portlet Factory provides powerfultechnology for speeding the creation of service-oriented applications andportlets. It includes data services builders along with data integration buildersthat together automate the process of creating services from systems such asSAP and Lotus Domino. This services approach provides a clean way toseparate the back end services of an application from the presentation layer. Italso automatically creates testing support for back end services, and it enablesfront end presentation development and testing without requiring a back endconnection.• Many portlet variations from a single code base. With the profiling capabilityof WebSphere Portlet Factory, developers can easily create multiple portletWebSphere Portlet Factory V6.0.1 Getting Started Guide - 3 -

variations from one code base, without requiring any additional code changesor redeployment.• Automation of frequently occurring development tasks. By creating newbuilders, developers and architects can capture commonly used design patternsand company-specific business processes as reusable components for alldevelopers, enforcing application architecture and development best practices.Technology overviewThis section provides a technology overview of WebSphere Portlet Factory, starting withthe architecture, which is illustrated in Figure 1.Figure 1. WebSphere Portlet Factory application architectureThe first layer of the architecture stack pictured above is the data sources on the left.Data can be sourced from a number of different systems, including databases,enterprise applications such as SAP, collaborative platforms like Domino, and historicalor analytical data from products such as SAP Business Warehouse.The next two layers – services and portlets – can both be developed with WebSpherePortlet Factory Designer. The Designer tool is an Eclipse plug-in and runs seamlessly inEclipse-based products, such as Rational Application Developer.The last layer of the diagram illustrates the Portal server framework, which provides keyservices such as page navigation and creation tools, single-sign-on capabilities, usermanagement, built-in process server, and collaboration features such as instantmessaging.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 4 -

Key concepts: builders, models, and profilesWith WebSphere Portlet Factory, developers build portlets by snapping together asequence of components called builders. Each builder has a simple wizard-like userinterface and does the work of automatically generating or modifying part of anapplication. A builder implements an application design pattern.Builders are assembled in models, which are like application production lines. Eachtime a change is made to any of the builders in a model, the application code isregenerated, allowing the developer to iteratively develop a custom portlet application.The builders generate all the application code, including JSPs, Java classes, and XMLdocuments.In addition, developers can create multiple variations of a portlet from one code base,without requiring additional code changes or redeployment. This is done with theprofiling feature of WebSphere Portlet Factory. Different profiles can be created fordifferent user constituencies, based on any characteristics such as region, role, or groupmembership. The profiling technology is also used to support runtime configuration, sothat business users can control application functionality through a simple browserinterface. The net result is that WebSphere Portlet Factory allows companies to rapidlycreate adaptive applications that respond to change on demand – something traditionaltools and technologies simply cannot provide.Using builders to create portlets or servicesDevelopers use WebSphere Portlet Factory models to implement a portlet user interfaceor a data service. After creating a new model, the next step is to start adding buildersto the model, which will create the desired application code (see Figure 2).As described briefly above, builders are software automation components that capturedesign intelligence and automate the creation of code. Similar to customizable robots inan assembly line, builders perform specific software automation tasks, based uponinputs or parameters specified by developers. WebSphere Portlet Factory includes morethan 130 builders that automate a wide range of tasks, such as creating HTML from aschema or integrating with common back-end systems (like Domino, SAP, Siebel,databases, and so on).Builders are selected from the Builder Palette, which lists all the builders by category.The Builder Palette is shown in Figure 2.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 5 -

Figure 2. WebSphere Portlet Factory Designer – adding builders to a modelWhen a builder is selected from the palette, you are presented with the builder call editor(see Figure 3). The next step is to provide the builder’s inputs by typing in theappropriate inputs and using the builder’s various pickers and selection widgets.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 6 -

Figure 3. Editor for the Excel Import builderAfter the builder inputs are populated, when the OK or Apply button is clicked, thebuilder generates the appropriate code through a process called regeneration. When amodel is regenerated, each builder in the model executes in sequence and createspieces of your application, such as JSP pages or Java methods. Each time you changea builder input and click OK or Apply, regeneration occurs. Regeneration is similar to theprocess of “recalculating” a spreadsheet, the difference being that WebSphere PortletFactory regenerates the portlet code, rather than a set of numbers.You can see all of the code generated by the builders in your model by using theApplication Tree view. To see the code generated by a particular builder, click on thearrow in the right-most column of the Outline view (the “Link to WebApp Tree” button).Figure 4, shows the model after the Excel Import builder has been added, and the Linkto WebApp Tree button has been pressed. As a result, the Application Tree viewhighlights the code created by that builder, which includes a schema that describes theExcel data, an XML variable that will hold the data, and a data service that can beinvoked to retrieve the data and place it in the variable.Figure 4 shows the Application Tree view with the code created by the builder in themodel.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 7 -

Figure 4. Application Tree viewDevelopment continues by adding builders to your model until you have the desiredfunctionality. Along the way, you can test the model by running it from the Designer tool,using any application server to see the intermediate results. You do not need to deployto the portal unless you need to test portal-specific features such as portlet-to-portletcommunication.When working with pages and user interface elements of an application, the graphicalDesign view provides an up-to-date WYSIWYG view of your pages. You can selectpages by clicking in the Application Tree or in the Pages tab. From the Design view,you can right-click on elements to bring up a list of suggested builders that can beapplied to the selected page element.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 8 -

Figure 5. Design view for one page of a portlet modelDevelopment with WebSphere Portlet Factory is an iterative process. If you do not likewhat a builder has created, you can go back, change the builder’s input values, andhave the entire portlet application update instantly. Or, you can add additional builders toyour model that modify what other builders have created. You can also import your ownJava code, HTML, style sheets, and JSPs to get the exact functionality desired. In short,WebSphere Portlet Factory supports rapid prototyping, and it also includes all thenecessary capabilities for you to turn your quick prototype into a production-readyportlet.Dynamic profilingOften, companies want to be able to tailor their portlets for different users, based upontheir roles, personal preferences, or other types of contextual information. To implementcustomized portlets or portlets that adapt based upon information about the user,developers typically have had to write conditional logic or copy and paste the portletcode, creating versions for each unique variation required. These approaches tocreating customized portlets are usually cost-prohibitive and, ultimately, a maintenancenightmare.A key feature of IBM WebSphere Portlet Factory is dynamic profiling. Profiling solves themaintenance and scalability challenges that companies face when they try to buildportlets that are customized for personal preferences, roles, groups, geography, andbrand for individual users. With profiling, developers can very easily build portlets thatautomatically adapt and tailor themselves to the preferences and characteristics of eachperson using the portal.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 9 -

A profile contains a set of parameters that vary the way an application behaves. A profilefeeds values into builders based on user identity or other contextual information (suchas language or brand). Using profiles, you can automatically generate differentvariations of a portlet (from the same model) for different users, customers, or situations.Deployment overviewWhen your model is complete, you deploy it to the portal. To do so, simply add oneadditional builder to your model called Portlet Adapter. This builder will indicate that youwant to deploy your model as a portlet. (Even with the portlet adapter in your model, youcan still run it standalone and as a portlet.)Creating a WebSphere Portlet Factory projectThe first step for developing with WebSphere Portlet Factory is to install the product andconfigure a new project.Step 1: Install WebSphere Portlet Factory.Install WebSphere Portlet Factory. Run the installation program as documented in theinstallation guide provided with your product. The guide appropriate to your productversion is located at the top level of the IBM CD. WebSphere Portlet Factory supportsapplication deployment on WebSphere Portal Server.Step 2: Create a project that includes WebSphere Portlet Factory features.After installing WebSphere Portlet Factory, the next step is to create a Web applicationproject. A project is the foundation of a portlet or application, and contains all theartifacts required to build the application. The easiest way to get started is to follow theQuick Start with WAS CE tutorial included with WebSphere Portlet Factory.1. Select Start Programs IBM WebSphere Portlet Factory Tutorials.2. Select Quick Start with WAS CE.3. Use the instructions to start WebSphere Portlet Factory Designer and to create anew project (up to Step 3 in the tutorial).4. When you reach Step 4 in the tutorial (adding the Tutorial and Samples Featureset), also add feature sets for the specific data sources you want to use. Note thatsupport for relational databases does not require any additional feature set. Hereare some other feature sets for data integration:o Lotus Collaboration Extension (for Lotus Domino access)o PeopleSoft Extensiono SAP Extensiono Siebel Extensiono Excel Extensiono Lotus Web Content Management ExtensionTip: When you create your own applications in the future, add only those featuresets that you will actually use in your project. This reduces the size of the portletWAR file you are creating. If you want the samples feature set, consider creating aseparate project in Eclipse for these.5. Complete the rest of the tutorial and follow the instructions there to verify successfuldeployment. Make sure that you can run some of the sample models and that youcan make a change to a model and see your change when you run the model again.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 10 -

Creating data servicesAfter you have installed WebSphere Portlet Factory and created your project, the nextstep is to build the data services needed by your portlets. With the rich set of servicesbuilders included in WebSphere Portlet Factory, it is very easy to create portlets basedupon a Service-Oriented Architecture (SOA).Why use WebSphere Portlet Factory builders for SOAWith WebSphere Portlet Factory, you can quickly build portlets where the data and thepresentation layer are all in one model. For example, you can very quickly create anSAP portlet by creating a new model and then adding the SAP View & Form builder toyour model. This one builder allows you to quickly connect to an SAP BAPI and thengenerate input, results, and even detail pages. While this approach is very fast andefficient, it is not the optimal architectural approach.A better approach is to separate the back-end data access from the presentation layer,by creating two models – a service provider model (which accesses the back-end dataand services) and a service consumer model (which provides the front-end userinterface.) By using this approach, you can create a well-defined interface that separatesthe user interface from the back-end data. There are a number of valuable benefits tothis architecture, including:• Reuse - By encapsulating your back-end data and processes into a set of welldefinedservices, you can achieve high levels of reuse across your project.• Flexibility – You can enable independence and flexibility between thepresentation and the services layers, both at implementation and indeployment. For example, you can dynamically swap out the data service thatdrives a portlet user interface, without having to change the user interface.• More efficient division of labor – By breaking development into two primarytasks – creating services and creating user interfaces – you can allocate yourresources more efficiently. Some developers can focus on creating the dataservices, while others can create the user interface or service consumermodels. Teams of developers can work independently on the layers without theneed to constantly coordinate and adjust to modifications made on the otherside.• Automatic service testing support – When creating a service provider model,you can automatically generate a test harness, for easy testing of your backend functionality without requiring front end development.• Offline or disconnected development – By leveraging the service builders,development can proceed without requiring access to the targeted back-endsystems, which helps ease and speed development, especially for the userinterfacedevelopers.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 11 -

Figure 6. Diagram showing the use of a service provider model to access data from arelational database, with separate portlet or consumer modelsCreating a service provider modelThis section details the steps required to build a service provider model.Step 1: Create a new, empty (service provider) model.Often, for clarity, it makes sense to save all of the data services for a project within onefolder. For example, if you are creating a manufacturing portlet, you might save yourservice provider models in the folder WEB-INF/models/manufacturing/data.Step 2: Add a data integration builder to your model.The following table should help you determine which builder to use for which back-endsystem:System or Data SourceDatabasesDominoExcelJava classPeopleSoftBuilderSQL CallDomino Data AccessExcel ImportLinked Java ObjectPeopleSoft Component InterfaceWebSphere Portlet Factory V6.0.1 Getting Started Guide - 12 -

SAPSiebelREST Service (Representational StateTransfer)Web ServiceXML DataSAP Business Warehouse/MDXSAP Function CallSiebel Business ComponentREST Service Call builderWeb Service CallWeb Service Multiple OperationsVariable or Import to XMLSAP BW Data AccessFor example, if you want to get data from a JDBC-compliant database, you need to adda SQL Call builder to your model, which lets you specify inputs such as your SQLstatement. After you fill out the builder’s inputs and save the builder, it will then generatea schema that describes the data, a variable typed with the schema, and an executemethod that, when invoked, executes the SQL query and places the returning data inthe variable.When creating services, schemas play an important role. Not only do they describe thedata being returned by the back-end system, but they are also heavily used by thebuilders within WebSphere Portlet Factory to generate the portlets’ user interfaces.Builders like SQL Call, Domino Data Access, Excel Import, PeopleSoft ComponentInterface, SAP Function Call, and Siebel Business Component automatically generatethe schemas for you.Step 3: Add a Service Definition builder to your model.This builder creates the underlying support for an initially empty service, provides anoption for exposing the service through WSDL, and names the service. When adding theService Definition builder, be sure to select Add Testing Support so the builder willauto-generate Web pages for testing the service and all the operations in the service.Step 4: Add one or more Service Operation builders to your model.This builder adds an operation or method to the service defined by the Service Definitionbuilder. The operation can invoke any data access support available in the model. Asdescribed above, data access is usually provided by using one or more back-endintegration builders, such as SAP Function or SQL Call, but can also be provided by alinked Java object or any data-returning method.For example, if you are creating a service that gets orders data from a JDBC-compliantdatabase, you first need to add a SQL Call builder, as described above. Then, you willadd a Service Definition builder, giving the service a name (such as OrdersData).Finally, you will add a Service Operation builder, giving the operation a name (such asgetOrderDetails), pointing at the execute method to wrap as a service, andspecifying the input and result schemas.Note: The Service Operation builder:• Does not invoke the external data access API. Other builders (such as the SQLCall builder), make the calls and bring the data into the Web application.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 13 -

• Can transform data from the structures used by the back-end system buildercalls into the desired structures for the service being defined.Step 5: Test the model by running it.Use the auto-generated test harness to ensure that service is operational. Remember,you need to select the Add testing support option in the Service Definition builder inorder for this to work. In addition, if your service takes inputs, you can set default inputvalues in the Service Definition builder, by selecting Specify Default Inputs in theTesting Support section.Step 6: Add additional operations to your service.It is often useful to define a service with multiple, related operations. Sometimes thedata sources can even come from more than one back-end system. For example, acustomer information service can define operations to return a customer list (based onsearch criteria), customer detailed information, customer orders, customer complaints,and so on.If you want to expose multiple operations in your service, then you will need to addadditional data integration builders and service operation builders to your model for eachoperation that you want to include in your service. For the orders example described inStep 4, you might want to add another operation called getOrdersbyCustomer, whichwill return all of the orders for a given customer. To add this operation, you would add aSQL builder that defines the query (since the data in this example comes from adatabase) and then add another Service Operation builder that wraps this latest SQLcall execute method as a service.Step 7: Generate a stub model.After your initial service is tested, you might want to generate a stub model, which is anentirely self-contained model that declares the same service, operations, schemas, andso on, as the original service, but which does not require back-end access. To generatea stub, simply provide a name for your stub model and click Generate Stub in theService Definition builder.Stub models are often very useful for team development projects, where there are somedevelopers creating the back-end access and others who are creating the front-end forthe portlets. For example, assume a user interface developer needs a service you aredeveloping in order to start working on her portlet. You can generate a stub and give it tothe user interface developer. This stub can easily be swapped out for the final servicewhen it is complete. Stub models are also useful when your back-end system is slow inresponding or has limited availability. By using stubs, you will save considerable timebecause the stub model does not need to access the slow back-end system for everyregeneration cycle.Additional featuresThis section provided a high-level overview of the most common steps used to createdata services. Periodically, you will need to perform additional steps to create your dataservices, which may include transforming the data, performing some pre- or postprocessingactions, and adding error handling. Common builders used for these types oftasks include Action List, Error Handler, and Linked Java Object builder.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 14 -

Given the scope of this document, it cannot cover all of these steps, nor can it detail allof the service features provided by WebSphere Portlet Factory, which includes dynamicservice mapping, service interface support, automatic generation of servicedocumentation, and more. Refer to the WebSphere Portlet Factory help system for moredetails on these additional capabilities. There are also some samples showing how tocreate services for various back end data sources available at:http://www-10.lotus.com/ldd/pfwiki.nsfDeveloping the portlet user interfaceThis section describes the high-level steps for creating your portlet user interface.Creating a service consumer modelIf you are following best practices, the first step in creating your portlet user interface isto create a new service consumer model, to which you will add all of the buildersnecessary to call the appropriate data services and generate the portlet user interface.The next step is to add a Service Consumer builder to this model, which is used toprovide access to a public service created by the builders in a service provider model.The Service Consumer builder can be used to add all operations within the selectedservice provider to your model, or you can optionally select one operation to add to yourmodel.Note that you may add multiple service consumer builders to your model to accessmultiple service providers.For an example of a service consumer model, navigate to the samples folder underWEB-INF/models/samples/gettingstarted/OrdersServiceConsumer.model.Note that you must first install the Tutorials and Samples – Applications feature set toaccess this sample.Creating the initial presentation interfaceAfter a service is available, the next step is to build the portlet user interface. The mostcommon builder to use for this is View & Form. This builder is a high-level builder thatautomatically generates pages for viewing and editing data from data services.View & Form builderThe View & Form builder can be used to create a portlet with a view page that displaysthe results from a service operation, with optional pages for input, details, and update.As with other builders, you can selectively add the functionality that you require. Forexample, you can have this builder just create the view page and not the input, details,and update pages.Here are a few examples of portlet use cases ideally suited to the View & Form builder:• A portlet displays a list of expenses, and allows users to click to see the detailsof an expense, and then update that expense.• An employee directory portlet enables users to search for an employee andview a table of results or the selected employee.• A “Personal Information” portlet in an HR employee self-service applicationallows users to view and edit their own personal data.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 15 -

The View & Form builder automates the creation of:• A view page that displays a table or single record of data.• An optional input page for the specified view operation, with optional validation.• An optional detail page that displays either data from the selected row in theview page or data from another data service or method.• An optional update page for editing details or results data.• Navigation between the pages (buttons).Alternative methods for creating the initial presentationIn some cases you may need to create the initial presentation for a portlet using acombination of other builders instead of using View & Form. See section below on“Creating the initial portlet user interface.”Adding builders to achieve the exact functionality you needAfter you have created your initial presentation page or pages, the next step is usually toadd additional modifier builders that add new features to your portlet. For example, ifyou use View & Form builder to create a page with a table of service results, you canthen add a Data Column Modifier builder to rearrange or hide columns, or to add columnsorting functionality. Or, if you want to add a navigation link, you can use a Link builder.The development process then continues by iteratively making changes to the modeland testing them out. At any time you can open any of the builders in the model andchange any of the values. You can also temporarily disable any builders, by using theright-click menu on the builder in the Outline view.As you continue to customize your application by adding and editing builders, thenumber of builders in the model will increase. As a best practice it is recommended tokeep the number of builders in a model under 50, since models larger than that tend tobe harder to work with. In order to keep the number of builders small, you can usebuilders such as Linked Model and Model Container to make your application moremodular.Selecting builders for common tasksThis section lists common tasks and describes the builders that are typically used toaccomplish each task. Note that this section does not cover all of the builders containedin WebSphere Portlet Factory. Rather, it covers the most commonly used builders.• Creating services• Creating the initial portlet user interface• Working with tables, columns, and data layout• Working with variables and schemas• Controlling the validation, formatting, labels, and behavior of data fields• Using actions and events• Adding navigation and page actions• Adding and controlling page elements• Using Ajax and related techniques• Integrating WebSphere Portal features• Sharing functionality or resources across models• Supporting translation and localized stringsWebSphere Portlet Factory V6.0.1 Getting Started Guide - 16 -

Creating servicesTaskI want to get access to a data store.BuilderUse one of the following data integrationbuilders:• SQL Call (relational databases)• Domino Data Access (Lotus Domino)• Excel Import• Linked Java Object (Java class)• PeopleSoft Component Interface• SAP Function Call• Siebel Business Component• Web Service Call or Web ServiceMultiple Operations (any existing webservice)• REST Service Call (any existing RESTservice)• Variable or Import to XML (XML file ordata)• SAP BW Data Access (SAP BusinessWarehouse MDX)I want to create a service with one ormore operations. I may use this servicefrom another WebSphere Portlet Factorymodel using lightweight Java execution,or I may make it available to otherapplications via WSDL and SOAP.I want to generate a service testharness for testing a service.I want to create a stub service model,so that I can create a presentation modelusing my service interface but withoutneeding the actual back endimplementation.Service Definition and Service OperationDefine the overall service settings withService Definition, then add one or moreoperations with Service Operation. Select“Generate WSDL” from the ServiceDefinition builder to make the serviceavailable via WSDL.Service DefinitionEnable the “Add Testing Support” input, inthe Testing Support section. When you runthe service model, you will get an indexpage with a link for each service operation.You can provide default values for serviceinputs by selecting “Specify Default Inputs”in the Testing Support section.Service DefinitionEnter the desired name of the stub model inthe “Stub Model” input, and then click the“Generate Stub” button.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 17 -

I want to switch between serviceprovider implementations withouthaving to edit my consumer models.For example, I want to automatically usea stub implementation of a service.I want to make a service available toother applications using WSDL andSOAP.I want to transform data between aschema used by my back end data andanother schema.Use the Service Mapping Registryfeatures of the Service Consumer builder.Service mapping is controlled with the XMLfiles in the WEB-INF/config/service_mappings folder of aproject. For more information, search inHelp Contents of the product for “ServiceMapping Registry”.Service DefinitionEnable the “Generate WSDL” input. To getthe URL of the WSDL, enable the testingsupport and run the model. The test indexpage has a link to the WSDL URL.Use the Service Operation builder forsimple mapping. For more complex XMLmanipulation, use Java code thatmanipulates IXml, accessing the Java codewith the Linked Java Object builder.Creating the initial portlet user interfaceTaskBuilderI want to access a service created in aservice provider model.I want to create view and form pagesbased on data from a data service. Theview page will display a table or singlerecord of data from the service results.I may also want to create associatedpages such as:• An input page for the specifiedoperation, with optional validation.• A detail page that displays eitherdata from the selected row in theview page or data from another dataservice or method.• An update page for editing details orresults data.Service ConsumerThis builder makes a service available foruse. The service must be defined in aservice provider model, which is a modelthat uses Service Definition and ServiceOperation to create a service.You can also access a web service usingWeb Service Call, but the recommendedbest practice is to put the web serviceaccess in a provider model so that you canuse features such as the automatic testharness and the stub service modelsupport.View & FormAs described above, the View & Formbuilder can be used to generate severalcommon UI page patterns.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 18 -

I want to implement a details pagetriggered by clicking on a row in a table.I want to create an input page for mydata service operation, which does notreturn result data.I have some existing HTML (or JSP)that I want to use in my portlet and adddata or other elements to.I want to create a chart.Use the View & Form builder to create yourtable and select the choice for “Create linkto details”. You then have three choices forhow to handle the link action:• The details page can show the dataalready retrieved in that table row.• The details page can show data fromanother operation, such as a serviceoperation that retrieves details data. Inthis case, you will need to use the InputOverrides feature of the ServiceConsumer builder to specify theservice inputs needed to retrieve thedetails data. These inputs can typicallycome from the SelectedRowDatavariable created by the View & Formbuilder.• The link can be used to execute anyaction you specify, such as an ActionList or a page.With any of these link types, the View &Form builder automatically creates a_SelectedRowData variable that ispopulated with all the contents of the rowthat was clicked. Typically you will selectvalues from this variable when choosing theinputs you need for your row action.Input FormCreates an input page for a data serviceoperation or a method. It is much like View& Form input page support, but the nextaction after submitting the input form is auser-specified action. This builder issuitable for operations that do not haveresult data to display.Imported PageAdds an existing HTML or JSP page to thecurrent Model. By using Imported Pagebuilders, you can develop your HTML orJSP code in your favorite editor and thenimport the results into the Designer. Afteryou import a page into the Designer, youcan use builders to modify those pages.Web ChartsThe Web Charts builder adds a chart to apage at a specified location. The data forthe chart can come from a variable, aservice operation, or any other data sourcein the model.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 19 -

I want to use Workplace Forms in myportlet.Use the Lotus Forms Embed builder toembed a Workplace Form on a page. Theform is retrieved from the forms repositoryand rendered to the user using theWorkplace Forms Viewer.Use the Lotus Forms Launch builder toadd a control (button or link) to a page inyour model to open a Workplace Form. Theform is opened in a separate browserwindow.I want to add some structured data toa page for input or viewing and havefields automatically generated based onthe schema of the data.I want to quickly create a simple HTMLpage for use with other WebSpherePortlet Factory builders.I want to create view and form pagesbased on data from a specific back endsystem.I want to use Flash in my portlet.Data PageCreates a structure based on the XML datain a variable and renders this structure as aform (both input and display) on a page.The structure created by the data pagedescribes the data to be displayed as wellas how to render the data on the form. Aschema associated with the data on whichthe data page operates can determine howthe data gets displayed as can the HTMLpage associated with the data page.Note that the Data Page builder is usedunder the covers by high-level builders suchas View & Form.PageUsed to create a simple user interface usingHTML or JSP markup. You can enter orpaste markup directly into the builder.Domino View & Form, SAP View & Form,PeopleSoft View & Form, Siebel View &FormThese are back end specific builders thatcan be used to create the initial userinterface for a portlet. However, with thesebuilders you don’t get the benefits of aservice provider/consumer architecture.FlashDisplays an Adobe Flash SWF file at aspecified page location.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 20 -

Working with tables, columns, and data layoutTaskBuilderI want to clean up my portlet by hidingcolumns that do not need to bedisplayed.Rich Data Definition (RDD)RDD is a powerful builder that you will usein most, if not all, of your Models. Thisbuilder lets you select a schema in yourModel. For each field in the selectedschema, you can specify labels, controltypes, lookup tables, formatting, validation,and much more – just by using a singleinstance of this builder.Alternatively, you can use the Data ColumnModifier builder which is described below.I want to add sorting to the columns inmy table.There are a few different ways of addingsorting:Rich Data Definition – For each of yourcolumns that you want to add sorting to,select the associated element in the RDDbuilder, and select one of the base datadefinitions that specify sorting. ORData Column Modifier – This builderallows you to modify table columns,including adding sorting.I want to:Rearrange the order of the columns in atableAdd a counter column to my tableChange the alignment of my columnsAdd an “Edit” column for editing recordsin your tableAdd a “Delete” columnData Column ModifierThis builder controls the tabular display ofone of the "container" elements in the databeing managed by a Data Page builder call.When you choose one of the availableelements, the builder editor displays a tablethat lists all the child elements in theselected element. This table contains inputsallowing you to configure the displaycharacteristics of each column in the tableas well as adding columns and rearrangingtheir placement.I want to create a data view that allowsusers to expand and collapse the databy category. This type of control is oftenreferred to as a “twisty” by Domino users.Category ViewThis builder adds collapsible sectionsassociated with one or more columns ofcategorized or sorted data. A user can clickon an icon to expand and collapsedisplayed category data. Note that thisbuilder requires that a column of the datacontains category values.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 21 -

I want to allow users to expand andcollapse data at a specific location.Collapsible SectionThis builder arranges for an additionalinformation section to be displayed (orhidden) when the user clicks a specifiedarea on the page.I want to create visual grouping ofdata fields for display in forms.Data Hierarchy ModifierThis builder lets you select data from abuilder such as View & Form or Data Page,and create new grouping within the datastructure.I want to create newspaper-stylecolumns for form data.Form LayoutThis builder lets you select form data for apage, and divide it into multiple verticalcolumns.Working with variables and schemasTaskBuilderI want to create an XML variable.The Variable builder let you type or pasteXML data; the Import To XML builder importsan XML file.I have an existing schema file (.xsd)that I want to use in my Model.SchemaImports a schema for use in your Model.I want to create a simple schema.Use Variable builder to create an XMLvariable with the desired structure, and thenuse Simple Schema Generator to make aschema from that Variable.I have a schema, but I do not have anysample data to go along with it.A nice feature of the variable builder is that itcan generate some sample data for you.Simple select the Variable builder and use theType select to navigate to your schema. Afteryou have selected the schema, a “CreateSample Data” button will appear. Click this togenerate your sample data.I have an existing Java Bean that Iwant to use in my application.Linked Java Object.Once you have used Linked Java Object tomake the Bean available in your model, youcan use the Data Page builder to generatepage fields directly from Java Bean properties.Java/XML Converter can also be used toconvert beans to XML.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 22 -

I need to transform data betweenschemas.Use the Service Operation builder for simplemapping. This is usually done in a serviceprovider model. For more complex XMLmanipulation, use Java code that manipulatesIXml. See the Javadoc for the IXml class fordetails.I want to share some data acrossportlets. For example, I may want tocreate a “filter” portlet that lets usersspecify values that are used by multipleother portlets on the same or differentportal page.Shared VariableThis builder marks a variable so that it can beshared across portlets and models.I want to reduce the session size formy application.Discardable VariableThis builder modifies an existing variable sothat it is not stored in session.Controlling the validation, formatting, labels, and behavior of data fieldsTaskBuilderI want to add formatting or validation toa field or to an element in a schema. Forexample, I want to:Format the field (for example, format thedata in the acceptable date format)Translate an expression (for example,remove dashes from a formatted string tothat it can be properly saved)Validate the field being submitted (forexample, ensure that the Birthday field isa date).Although either Data Field Modifier (DFM)or Rich Data Definition (RDD) can helpwith these tasks, RDD is the best choicebecause you can use this builder to encodeand reuse detailed field behaviors. You canenable reuse at the schema level bycreating an RDD file for a particular schema,and you can also reuse a single sharedlibrary of common field types, with the"base" data definition functionality.To generate your own data definition file,use the RDD’s builder interface to set theappropriate formatting, validation, and soon. Then, scroll down to the bottom of thebuilder and press the “Create DataDefinition File” button.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 23 -

I want to make my column nameseasier to read. For example, rather thandisplaying CUSTOMER_NAME, I want tojust display the word Customer.The Data Column Modifier and Rich DataDefinition builders can be used to changethe labels that are displayed in your portlet.The Localized Resource builder can alsobe used to change column and field labels,and it can support multiple languages. Itlets you pick a resource bundle, which itimports into a variable in your Model. Youcan then use the values from that variable tolocalize text strings in your model, such asbutton or column labels. After you haveadded the Localized Resource builder toyour model, the next step is to open up thebuilder that created the fields (View & Formbuilder or some other builder based on DataPage), and scroll down to find the LabelTranslation section. From there, select thelocale data or resource bundle you areusing.I want to change the behavior of a fieldin my view or my form. I want to:Make the field a data entry control (suchas a text input, text area, select, or checkbox).Make the field view only (for example,text or image).Make the field an action field (such as alink, button, or image button).Use Data Field Modifier to change thebehavior of fields created by Data Page, orany higher-level builder that uses Data Page(for example, View and Form).Rich Data Definition can also be used formuch of the functionality provided by DataField Modifier. Note that some of thefeatures of Rich Data Definition areavailable in the XML files used by RDD andare not available in the RDD builder userinterface.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 24 -

I have a value that I want to translateinto a meaningful name. For example,instead of displaying the DepartmentCode, I want to display the DepartmentName.I have an edit form that allows users toselect a name (like Department Name),but I really need to save the associatedvalue (like Department Code).I want to populate my select list (orsimilar control) with a value that is notreturned from my database, such as ablank or an option such as “any.”The most common way to do this is byadding a Lookup Table builder to yourModel. The Lookup Table builder creates alookup table, which is used to translatebetween some computer-readable ID and ahuman-readable name, often the result of adatabase query. The table also caches theresults across different users, including theopportunity to prevent data from becomingstale. This builder:• Lets you access a data source byentering a SQL statement, pointing toan XML variable, or typing in someXML.• Adds to the query results anyname/value pairs you want to include inthe select list (for example, blank).• Creates methods that do the translationbetween name/value pairs.Next, add the relevant page control builderto your Model, pointing it at the LookupTable builder. Builders that work withLookup Table include Data Field Modifier,Select, Text, and Radio Button Group.You can also have the Rich Data Definitionbuilder (RDD) automatically create andapply a lookup table. This can beespecially useful if you use the same lookupnumerous times. See the help for RDD formore informationOne of the builders I used in my Modelgenerated a label that I do not like. I wantto shut off label generation.ORI want to provide my own label for thefield.Data Field ModifierData Field Modifier is a builder that is usefulfor a number of different tasks. Basically,this builder can be used to control the pageelements created by Data Page builder (aswell as the higher-level builders thatleverage Data Page).This builder lets you select one or morefields and one or more data types (likedouble, string, and so on). You can thenperform modifications including hiding,formatting, labeling, and determining thedisplay of child elements.Data Column Modifier and Rich DataDefinitionThese builders can be used to specify fieldlabels.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 25 -

Using actions and eventsTaskBuildersI want to perform some processing inmy Model such as:Calling a method and then returning apage.Executing several back-end callsbefore loading the initial page in myModel.Action ListThe Action List builder allows you to add aset of one or more actions to your WebApp.Typically, all Models must have an action inthem called main. Most of the higher-levelbuilders automatically create this action foryou. However, this builder includes theability for you to override this feature, so thatyou can add your own main action list toyour Model, which can perform whateverprocessing you need.I want to perform a conditionalstatement (for example, if two variablescontain the same value, perform anaction), but I do not want to write Javacode to do this.Within the Action List builder, you can buildconditional statements without having towrite Java code. Use the picker underneaththe actions user input to navigate to Special-> Conditional. From there, you can select if,else, endif, and build up statements that willexecute an action or return a page basedupon conditional logic.I want to debug by sending SystemOutmessages to the console.Within the Action List builder, select theSystemOut option underneath “Special”within the action picker. This builder sendsSystemOut messages to the applicationserver console, and to the debugTracing loglocated in the deployed .../WEB-INF/logsdirectory. For example, in WebSpherePortal, the log files for running as a portletare found in the deployed portlet WAR'sdirectory. If the portlet is run standalone, logfiles can be found in the deployed enterpriseapplication's directory.I want to assign or append values tovariables. In other words, I want toappend or replace what is in a givenvariable with the results of a method call,an argument, or another XML variable.Within the Action List builder, select theAssignment option underneath “Special”within the action picker.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 26 -

I want to use some Java code in myModel.Linked Java ObjectThis builder lets you point at a Java class. Itthen adds the public methods of that classto your WebApp, so you can call them fromany builder input where you specify anaction.In some scenarios, you could also use theMethod builder. This builder lets you easilycreate a simple Method, which can makecalls to display pages, call methods, orexecute service calls.Note that if you need significant amounts ofhand-coded Java, you should write a Javaclass and bring it into the Model with aLinked Java Object builder instead of usingMethod builders. This will make the Modeleasier to manage, and the code assistanceis better in the Eclipse Java editor. Ingeneral, Method builders in your Modelshould only contain small amounts of “glue”code.I want to add error handling to myModel.Error HandlerThis builder catches Java exceptions thatmay occur within the run-time execution of aWeb application’s actions. The errorhandling can be specified on any action,such as a page, method or action list. Youcan also set a general handler for the entireapplication to be used if an action has noerror handler. This type of error handling ismodeled closely after the Java try-catchexception handling and JSP page directive,where each page can set the error page atdesign time. In all of these cases the lowestlevelhandler (catch) is called to handle theexception.I want to add caching to my Model.For example, I am populating anEmployee select list from a database call.Since the list of employees does notchange that frequently, I want to cachethe content when I have received it fromthe database.Cache ControlThis builder caches the output of a specificaction within a Model. Note that this cachingis across users: all users in a given profilewho access that Model will be presentedwith the same cached data. When thiscaching is suitable, it can substantiallyimprove performance.Service Operation and Lookup Tablebuilders also have built-in caching options(this is implemented under the covers withCache Control).WebSphere Portlet Factory V6.0.1 Getting Started Guide - 27 -

I want to establish communicationbetween portlets using simplebroadcast events.Event DeclarationEvent HandlerUse Event Declaration to define the eventname and any arguments. Use the samedeclaration in both models (a convenientway to do this is to put the declaration in aseparate model and then to use ImportedModel to bring it into both models). In thesource model, call the “fire”method when you want to send the event.In the target model, use the Event Handlerbuilder to specify the action you want toperform when the event is received.I want to establish communicationbetween portlets using portlet wiring orClick-to-Action.Cooperative Portlet SourceCooperative Portlet TargetUse Cooperative Portlet Source in thesource model. Also in the source model,call the “fire” method whenyou want to send the event.. In the targetmodel, use the Cooperative Portlet Targetbuilder, and then use the Event Handlerbuilder to specify the action you want toperform when the event is received. TheOutput information in Cooperative PortletSource must match the Input informationspecified in the Cooperative Portlet TargetBuilder.Adding navigation and page actionsTaskBuilderI want to add an action control to a page,such as a Button, Link or a clickableimage.ButtonImage ButtonLinkThese builders can be used to add actioncontrols to a specified page location. Theaction can be a model action or anexternal URL. Note that if the action ispart of a form, you should select “Submitform and invoke action” as the ActionType.I want to specify a form action to runwhenever a form is submitted.Form Submit ActionThis builder attaches an action to anHTML form. Specify the form’s locationas the Page Location input. When youuse View & Form builder to create a form,this builder is automatically used underthe covers.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 28 -

I want to run an action when a userclicks or types in the portlet.For example, when a user selects acustomer from a select list, I want to run anaction (for example, search a database andreturn a table of orders that belong to theselected customer).HTML Event ActionThis builder allows you to associate afunction with an HTML behavioralattribute. The HTML behavioral attributesare those that correspond to HTMLevents, such as OnClick or OnChange forINPUT tags. The HTML Event Actionbuilder can only define actions for theevents that a particular tag supports.To build the example described in the taskon the left, you would likely use thefollowing builders:Service Consumer, View & Form, DataField Modifier, Lookup Table, Selectand Variable to build the select list andpage.HTML Event Action builder, to call anaction (created by an Action List builder)on the onChange event. This action wouldget the appropriate orders from thedatabase and return the page.I want to generate a pop-up menu withoptions when a user clicks in a certain partof the page.I want to provide a link or button fordownloading or launching a file.I want to create a link in my portlet thatlinks to a different portal page.Contextual MenuAdds a pop-up menu and its menu itemspop up when users click a specific link,button, or icon.Content Launch ActionAdds a button or link to a page that opensa file or resource that might require anadditional plug-in to view or handle thecontent. For example, if you want tolaunch a spreadsheet or video file from apage.WebSphere Portal LinkWith this builder, you can link to anotherportlet or page in WebSphere Portal.The object you link to is referenced with aWebSphere Portal resource identifier.See the builder help for more information.I want to create a portlet that includes tabsto navigate between the various pages inmy portlet.Page TabsThis builder adds tab navigation to a setof pages in a model. The tabs are addedto all the specified pages.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 29 -

I want to add paging controls to myportlet, for paging through a large resultdata set.Some of the higher-level builders likeView & Form include built-in support forpaging. If you are not using one of thesebuilders, then the best approach foradding paging is to use the Data FieldModifier or Data Column Modifierbuilder. Each of these builders haveinputs specific to paging.Note that the Paging Assistant builderoperates at a low level (and is actuallycalled by the Data Field Modifier andColumn Modifier builders). When invokeddirectly, the Paging Assistant may notcorrectly handle paging in all possibleconfigurations of Data Page.I created a form that accepts user input.When the user clicks submit, I want todisplay the results, but the results pagedoes not seem to display – even though Iam linking to the right action.Make sure to use "submit form" actionswhen updating server state and "link"events for navigation. For instance, if youadd a page action builder (Button, Link,Image Button, and so on) as the methodof navigating to the results page after aninput form is submitted, make sure youset the Action Type as “Submit form andinvoke action” or “Submit form and invokeURL”.For page-to-page navigation set theaction type to be “Link to Action” or “Linkto URL”.Adding and controlling page elementsTaskBuilderI want to show or hide a page elementbased upon certain conditions orbased upon a value.For example, I have a select list thatallows a user to select a product. When aproduct is selected, all of the partnumbers that make up that product aredisplayed in a table below the select list.When no product is selected, the tabledoes not appear.Visibility SetterUse the Visibility Setter to control what isdisplayed in your portlet.When you add a Visibility Setter builder to yourModel, there are several ways you can controlthe visibility of the user interface element theVisibility Setter is attached to. You can:Hide a control alwaysHide a control based on a valueHide a control based on the comparison of twovaluesIn the example described in the associatedtask, the table is being hidden by a visibilitysetter. If the value in a variable is blank, thenthe table is hidden. When the variable containsa value, the table will be displayed.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 30 -

I want to change an HTML attribute, butthe builder I am using does not allow meto modify or add an attribute.Attribute SetterThis builder modifies existing elements on apage by replacing or adding to any HTMLattribute values that those elements support.Use the Attribute Setter to add or modifyattribute values not set by the builders in yourModel. You can use this builder to change thefont, size, border, or any other supportedattribute for a control.I want to include the same page inseveral of my portlets.OrI want to include a page generated by abuilder onto an existing page. Forexample, when a customer is selectedfrom a select list, I want to display a tablebelow the select list.OrI want to insert the display of a page inanother model into a page in myprimary model.Inserted PageUse this builder to insert the contents of a Pagein the same model into a named location on aselected page (or pages).For example, you might want to insert a pagecreated by View & Form onto an importedpage.Model ContainerUse this builder to visually insert another modelinto a page. The other model can have its ownpage-to-page navigation without affecting theouter (container) model.I want to display some read-only text ona page.TextThis builder displays some text from a Variableor any other data source at a specified pagelocation.Add some client-side JavaScript to apage.Client JavaScriptThis builder can be used to add JavaScriptcode to a page.HTML Event ActionThis builder can be used to invoke JavaScriptbased on a client HTML event such as onClick,onChange, or onBlur.I have an existing tag library I want toleverage in my portlet.JSP TagThis builder automates the process of usingJava Server Page tags from a tag library. Afteryou select a tag library descriptor file in thebuilder’s editor, you can quickly select a JSPtag to use on the page. After a tag is selected,the builder displays the tag's attributes, so youcan easily specify the inputs.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 31 -

Using Ajax and related techniquesTaskBuilderI want to have just one part of a pagerefresh when the user does an action.There are two primary ways you can dothis:1. The page action builders (suchas Link, Button, and HTMLEvent Action) have an option forPost-Action Behavior that cantrigger a partial-page refreshinstead of refreshing the entirepage. The builders with thissupport include Link, Button,Image Button, HTML EventAction, and Form Submit Action.2. The Ajax Region builder can beused to mark an area of thepage, an entire page, or an entiremodel for partial refresh. Withthis builder, any actions triggeredfrom within the selected area willcause a refresh of that area only.I want to create a popup window withoutthe containing portal or other surroundingpages.I want my portlet to support drag and drop.Use a page action builder such asButton, Link, HTML Event Action toinvoke the page or action for the popup.Then in the Post-Action Behaviorsection, select “Show Advanced Options”and choose “Show action resultsstandalone: display no containing pages”.Dojo Drag SourceDojo Drop TargetTogether, these two builders provide dragand drop features on a page. Use theDojo Drag Source builder to designate alocation on a page as the drag source andto specify a single piece of data to bepassed to the target action. Use the DojoDrop Target builder to designate alocation on the page as the drop area andto specify a method action to invoke whenthe drop occurs. The method will bepassed the data from the drag source.The drag drop can operate on a singlepage or span across multiple pages, suchas in a portal environment.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 32 -

I want to support dynamic editing of thetabular data my portlet displays.Dojo Inline Edit BuilderThe Dojo Inline Edit Builder allows you toadd editing capabilities to a Data Pagefield so that it initially appears as readonlytext. The text can be edited byclicking a pencil edit icon next to the textfield. Once editing is complete, the userhas the option to cancel the changes orsave the results either to the page (as ahidden input) or submit the outer form.I want a text input field with Ajax-basedtype-ahead so that when a user types,they immediately see a drop-down list ofsuggestions.Ajax Type-AheadAttaches to an HTML text input field, andprovides what is generally known as "typeahead" functionality for that input. Thelist of choices for the drop-down can comefrom any XML in the model or from aLookup Table.I want to validate a form before the usersubmits it.I want to display a tooltip when the userhovers over a certain part of the page.I want the row the user hovers over to behighlighted in a different color.I want to use client-side events betweenportlets or within a portlet.Dynamic ValidationUsed to validate a user's input to fields ona form as the user is working with theform. This builder enables incrementalclient/server validation. It validates theform data and displays any errormessages whenever an input value isedited.Dojo Tooltip BuilderThe Dojo Tooltip Builder allows theapplication to display a popup text boxwhen the user's mouse hovers over aspecified target on a page. The tooltip textcan be a simple caption string, or anentire page in your model.HighlighterHighlights a row in a table (or a field in aform) as the user's mouse moves over it.Event DeclarationClient Event HandlerIn the Event Declaration builder, select"Use client side delivery". Then use theClient Event Handler builder to handlethe event that has been marked forclient-side delivery.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 33 -

I want to access data – HTML, XML, orJSON – for use in client JavaScript.You can generate a standalone URL toany model page or action by using theWebAppAccess methodgetBackChannelUrl.To automatically generate JSON(JavaScript Object Notation) data fromXML data, you can use theXML/JavaScript Converter builder. TheJSON data can then be consumed byexisting or custom UI elements on theclient. This builder can be used inconjunction with the Link, Button, ImageButton, HTML Event Action, and FormSubmit Action builders, when Evaluateaction results as JavaScript is set as thePost-Action Behavior in those builders.Integrating WebSphere Portal featuresTaskBuilderI want to add portlet-to-portletcommunication such as Click-To-Action or Portlet Wiring.See above under Using actions and events.I want to integrate “people awareness”or SameTime chat capabilities into myportlet.People AwarenessThis builder can make names “peopleaware.”It interacts with the Lotus®Collaborative Components available withinPortal.I want to link to another portal pagefrom my portlet.WebSphere Portal LinkWith this builder, you can link to anotherportlet or page in WebSphere Portal. Theobject you link to is referenced with aWebSphere Portal resource identifier. Seethe builder help for more information.I want to add custom edit or configuremode options for business users oradministrators.To enable Edit or Configure support, youmust first profile the builder inputs that youwant to make available for runtimeconfiguration. Then specify the desiredEdit/Configure behavior in Portal in thePortlet Adapter builder.To create a custom UI for Edit or Configure,you must then create a customizer modelthat includes the Portlet Customizerbuilder. In the Portlet Adapter builder of theportlet model, specify your customizermodel as the “custom model” choice.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 34 -

I want to have different variations of myapplication for different Portal groups orroles.There are a few steps in doing this:- Profile the builder inputs that you want tovary.- Create a named profile corresponding toeach of the Portal groups or roles, and setthe profile values as desired for each profile.- In the Profile Set editor, in the SelectHandler tab, choose “WPS Group SegmentHandler” as the Profile Selection Handler.- From the Manage Profiles tab of the ProfileSet Editor, in the Advanced section of theEdit Profile dialog, select Add External andenter the name of the Portal group, Dothis for each profile.- In the Portlet Adapter builder for yourmodel, select “Do not expose in Portal tools”for your profile set.For more information, see the “Profileportlets” article available from the“Miscellaneous Techniques” link on theproduct documentation site referenced atthe end of this article.I have a model that I want to makeavailable as a portlet.Portlet AdapterAny model containing the Portlet Adapterbuilder becomes available as a portlet.When you first portlet-enable a model thisway, you must save the model file, then usethe Rebuild Portlet WAR command, toupdate the portlet WAR in WebSpherePortal.I want to implement single sign-on bystoring user credentials in WebSpherePortal’s credential vault.WPS CredentialThis builder provides methods for savingand retrieving credentials (user names andpasswords) from Portal’s credential vault.I want my portlet to support searchingfor people or groups in WebSpherePortal.Directory SearchProvides a way to search for people orgroups in WebSphere Portal or otherdirectories.I want my portlet to display contentfrom IBM Workplace Web ContentManagement.Lotus Web Content Management AccessAllows you to retrieve content andcomponents from IBM Workplace WebContent Management.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 35 -

Sharing functionality or resources across modelsTaskBuilderThere are common builders that I needto use in all of my Models. How do Iarchitect this?Imported ModelUse this builder to import the completebuilder list of a second model into yourmodel. In the simple case, you can importall the builders as is. If you want toparameterize builder inputs in the secondmodel, you can profile those inputs andset the Profile Handling input to “Setindividual inputs”.I want to reuse one or more pages from amodel within another model. How do I dothis?Model ContainerUse this builder to visually insert anothermodel into a page. The other model canhave its own page-to-page navigationwithout affecting the outer (container)model.I want to reuse the actions or methodsfrom a model within another model. Howdo I do this?Linked ModelUse the Linked Model builder to provideaccess to any method, Linked JavaObject (LJO), or action list in anothermodel. You can also access pages inthe linked model, but in general ModelContainer is better for reusing visualelements of another model.I want to have centralized automatedcontrol of all my field behavior for eachfield types. For example, I want all mydate fields to use a calendar picker withformatting and validation that I can control.Or, I want all my tax ID fields to useformatting based on regular expressions.Or, I want every input for a US state to usea drop-down list.Or, I want every model that uses aparticular schema to automatically use astandard set of behaviors defined for thatschema.Rich Data DefinitionThis builder can be used to automate allthe UI behavior for fields that aregenerated from schemas.I want define a common look and feel forpages in all the models in my project.See the section on Customizing the userinterface and styles for information onhow to use custom HTML layout pages,HTML templates, and style sheets tocontrol the look and feel of all the pages inyour application.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 36 -

I want to automate a common designpattern that I use in a number of models.You may want to consider creating acustom builder. See the WebSpherePortlet Factory product documentation formore information.There are a number of builder inputs inmultiple models that I always want tohave the same value, and I want to beable to edit that value in a single place.For example, I have SQL Call builders inmultiple models, and I want to be able toeasily edit the SQL DataSource name forall the builders and models.Profile all those builder inputs to the sameprofile set and the same profile entry.Then whenever you edit the value, all thebuilder inputs in all the models will beupdated automatically.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 37 -

Supporting translation and localized stringsTaskI need to support multiple languages for aportlet.BuilderThere are a few steps involved increating a multi-language portlet:• Put text strings that should belocalized into resource bundle(.properties) files. Some builderssuch as Data Page have support forautomatically generating a propertiesfile for a set of field labels.• Use Localized Resource as one ofthe first builders in your model andspecify your resource bundle.• In builders such as View & Formand Input Form, select yourresource bundle for "ResourceBundle Name". In some otherbuilders such as Data Page you canreference the LocaleData variablecreated by Localized Resource.• Profile the Language and Countryinputs of the Localized Resourcebuilder to the LanguageCode andCountryCode entries of thecom.bowstreet.profileset.SimpleLocaleValues profile set.See the sample article for localizingportlets on the product documentationsamples web site (see resources at endof this paper).Customizing the user interface and stylesMany times, developers are satisfied with the user interface generated by WebSpherePortlet Factory. Other times, developers would like to modify what the product generated– whether it is the style of the chart or the design of the portlet user interface. Thefollowing details the most common ways of achieving the style that you desire:Supply your own style sheets or HTML layout pages.The builders provided by WebSphere Portlet Factory include default HTMLlayout pages and style sheets (which provide styles for elements such astables, header cells, and alternating row colors). By changing these files, youcan easily control the design of your portlets.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 38 -

Note that the HTML layout pages that ship with the product contain named tagsthat indicate where key controls should be placed. If you want to move thecontrol to a different place on the page, simply move the named tag within theHTML file. If you supply your own HTML file and you discover that a control isnot appearing (but used to appear with the default HTML page), you probablydo not have the right tag name in your file.For example, the View & Form builder uses a default layout page with thefollowing named tags:You can create your own copy of this layout page and add any other HTML youwant on your pages. For example, if you want additional static text or graphicsaround the data area, you can add it here by putting it before and after the tablenamed “data”. Then you can specify your page in the View & Form builder,and that builder will insert the JSP code at the specified name tag locations.Typically, developers will only make small modifications (if any) to the HTMLfiles. They will create, for example, one default page from a builder for all oftheir portlets by copying and pasting the default page that comes with theproduct. This same page will then be used each time a developer on the teamadds the builder to a model. Note that in this scenario, the developers are usingthe page generation capabilities in WebSphere Portlet Factory to generatemuch of the user interface.Every so often, developers want to have pixel-level control over the placementof each field and control on the page (to the extent that browsers allow), andcannot achieve the desired look with the default HTML pages, HTML templates(described below), and the combination of modifier builders (like Rich DataDefinition, and so on). In these rare scenarios, developers can create their owncustom HTML pages that contain tags for each field that needs to be displayed.For example, suppose you want to create a page that displays order details,such as Order Number and Amount. The most common way to do this is toleverage the page automation capabilities of the tool to generate the tags (suchas order_number) into the HTML page. If you do not want to leverage the pagegeneration capabilities of the product, you can supply your own HTML thatcontains all of the tag names (like order_number) that you want to see on thepage. Note that the tag names must match the names within the associatedschema. Also note that this approach hard-codes tag names into your page. Ifthe underlying data or schema changes, you must update your HTML to reflectthe new tags.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 39 -

Modify or change the default HTML templates.In the higher-level builders like Data Page, you will notice inputs for HTMLtemplates. An HTML template provides instructions to the page automationbuilders and allows you to control the automatic generation of HTML.Most of the HTML generated for portlets is a result of data page templates.These templates describe how elements like tables and forms should begenerated. The templates create elements that reference styles defined in thedefault style sheet mentioned above.You can use one HTML template for all pages in an application to achieve aconsistent design or you may use different templates for different pages or setsof pages. HTML templates are used in conjunction with imported pages(Imported Page builder) which provide content layout, graphics and nongeneratedartifacts. They may also be used with style sheets as desired.Given some of the intricacies of the template technology, most developers tendto stick with the default templates that come with WebSphere Portlet Factory.Or, they swap these out with some of the other templates shipped with theproduct.For more information about HTML templates, refer to the WebSphere PortletFactory documentation.Debugging TipsHere are some techniques that may be useful when debugging your applications.1. Look for builder errors and warning messages in Designer. If there are errorsshown in the “Problems” view of Designer when you are editing a WebSphere PortletFactory model, you should track these down and resolve them, since these errors willlikely result in execution errors.2. Disable builders to temporarily simplify a model and isolate the problem. As inany development environment, simplifying an application to isolate a problem can makedebugging easier. In WebSphere Portlet Factory Designer, you can disable builders byselected them in the Outline view and then right-clicking one of the selected builders andchoosing “Disable”.3. Write data to system output to look at values during execution. There are acouple of ways to do this in a model:• In an Action List, you can use the SystemOut action in the Special category tooutput values. For WebSphere Portal, this system output is written to the Portalserver’s log/SystemOut.log file.• With the Debug Tracing builder, you can see the value of some data at a particularpoint during model execution. Specify the “Action to trace”, and for “Additionaldebug output”, select the value you want to see. This output is written to the WEB-INF/logs/debugTracing.txt file of the deployed WAR.4. Look for errors in the event.log file of the deployed WAR. When a runtime erroris detected during model execution, the details of the error will be logged in the fileWEB-INF/logs/event.log file. The exception details may help you determine the rootcause of the error.WebSphere Portlet Factory V6.0.1 Getting Started Guide - 40 -

5. Run with system tracing to see exactly what actions get executed. Systemtracing can be used to see all the high-level model actions during execution. Systemtracing also gives you a quick look at the performance of all the actions, so you canoften quickly spot a performance issue. You can enable system tracing in the “Run”configuration dialog for WebSphere Portlet Factory Models, on the “Tracing” tab. Thesystem tracing output is written to the system output file (for Portal Server, this is theserver’s log/SystemOut.log file).6. Use Java-level debugging. To set up Java debugging (with single-step,breakpoints, etc.), you can use the remote debugging capabilities of Eclipse. Seeinformation in WebSphere Portlet Factory product help for how to set this up.DeploymentThis section covers at a high level a couple of important tips and best practices fordeployment. For a more complete document on this subject, refer to the WebSpherePortlet Factory help system. A helpful document on project configuration and WARdeployment is located underneath Working with WebSphere Portlet FactoryOverview: Deployment Deployment Configurations in a nutshell. Another usefuldocument about deploying portlet wars is located underneath Tasks Working withWebSphere Portlet Factory Overview: Deployment Deployment for Production.Hint 1. Remember to add a Portlet Adapter builder to your model.The Portlet Adapter builder tells WebSphere Portlet Factory to add your model to theWAR file. If your model does not have a Portlet Adapter builder in it, it will not becontained in your WAR file.Hint 2. Change deployment properties by right-clicking your project and selectingProperties. In the Properties Window, expand WebSphere Portlet Factory andselect Project Deployment Configurations.After you have created your project, and can always go back and modify your projectproperties. For example, you might decide that auto-deploy of the portlet WAR file is tooslow, and you want to disable this feature. All of this is easily accomplished by modifyingyour project’s deployment configuration.Hint 3. Reduce the size of your WAR file by removing unnecessary files frombeing built into the WAR file.Suppose you have several samples, test models, images, and HTML files that you usedduring development, but are not required for your production portlets to work. In order toreduce the size of your WAR file, you can exclude these files from being deployed.There are two ways to do this:• Create a directory called **/nodeploy/**. Artifacts placed within thisdirectory are not included in a deployed WAR file. Note that you can create oneor more /nodeploy/ directories at any location within a project. You can thenplace within these directories all of the project artifacts that you do not wantincluded in the deployed WAR. When the WAR is built by the Ant scripts, thecontents of the /nodeploy/ directories will be excluded from the buildprocess.• Use the .excludeFromServer file. Artifacts listed in this file are not includedin a deployed WAR file. There are two versions of this file:WebSphere Portlet Factory V6.0.1 Getting Started Guide - 41 -

Resourceso One is a master version located in your feature set directory -install_directory\FeatureSets\Web-App_X.XX.X\Tools\antScripts\public\. If you want to alwaysexclude the same files from every project you create, then you shouldmodify this master excludeFromServer file.o The other version of this file is located at the root of every project youcreate. Since the most common scenario is to exclude artifacts on aproject-by-project basis, you will tend to want to utilize the project-levelexcludeFromServer file.This section provides other sources of information to assist you with WebSphere PortletFactory.• Builder helpWhen you have a builder opened for editing, you can get detailed informationabout the builder and the inputs it provide using either the Help button at thebottom of the editor or the F1 key.• IBM WebSphere Portlet Factory wikiProvides numerous articles and samples to demonstrate common techniquesfor developing models in WebSphere Portlet Factory, available at http://www-10.lotus.com/ldd/pfwiki.nsf• IBM WebSphere Portlet Factory customer discussion forumshttp://www-1.ibm.com/support/docview.wss?rs=3044&uid=swg27011853• IBM WebSphere Portlet Factory Red Bookhttp://www.redbooks.ibm.com/abstracts/SG247525.html?Open• Extension packagesYou can access additional documentation for the feature sets provided tosupport Domino, SAP, PeopleSoft, and Siebel back-end data sources from theWindows Start menu: Programs IBM WebSphere Portlet FactoryDocumentation.• IBM WebSphere Portal Information CenterThis set of documentation includes information about WebSphere Portal serveradministration, as well as portlet deployment and management. You can accessall published versions of the documentation athttp://www.ibm.com/developerworks/websphere/zones/portal/proddoc.html• IBM developerWorks has more articles and resources on Portlet Factory. Seethe WebSphere Portlet Factory Zone on developerWorks for links to theseresources:http://www.ibm.com/developerworks/websphere/zones/portal/portletfactory/WebSphere Portlet Factory V6.0.1 Getting Started Guide - 42 -

Trademarks• DB2, IBM, Lotus, Tivoli, Rational, and WebSphere are trademarks or registeredtrademarks of IBM Corporation in the United States, other countries, or both.• Windows and Windows NT are registered trademarks of Microsoft Corporation in theUnited States, other countries, or both.• Java and all Java-based trademarks and logos are trademarks or registered trademarksof Sun Microsystems, Inc. in the United States, other countries, or both.• Other company, product, and service names may be trademarks or service marks ofothers.IBM copyright and trademark information: http://www.ibm.com/legal/copytrade.phtmlWebSphere Portlet Factory V6.0.1 Getting Started Guide - 43 -