Leveraging the new Ajax features in IBM WebSphere Portlet Factory V6.0.1

Document options Document options requiring JavaScript are not displayed Discuss Sample code Rate this page Help us improve this content

Level: Intermediate

Stephen Cooke, Advisory I/T Specialist, IBM　
Abhishek Singh (abhisheks@us.ibm.com), Senior IT Specialist, IBM

13 Nov 2007

IBM WebSphere Portlet Factory gives you a toolset to speed development. Use builders to simplify the addition of Ajax-like features to your portlets. Follow along with a sample portlet application.

IBM WebSphere Portlet Factory V6.0.1 gives WebSphere developers a toolset to speed their development. Each new version of the product gives you additional builders, many of which are designed to simplify incorporating an expanded set of Web features into your work. The latest version of the WebSphere Portlet Factory, release 6.0.1, provides builders you can use to simplify the addition of Ajax-based features. This article describes these new builders and demonstrates their usage through a sample portlet application. You should have a good understanding of building portlets using WebSphere Portlet Factory within either Eclipse or IBM Rational Application Developer for WebSphere Software.

WebSphere Portlet Factory gives you a Rapid Application Development toolset for building portlets. It empowers you with new builders to add both Ajax- and Dojo-based features to your models. These builders provide support for rich user interface elements such as dragging and dropping objects within or across portlets, inline editing of portlet page views, and overlay or popup windows that display additional data as the mouse hovers over a specified region of the page.

This article provides a basic background on Ajax and Dojo, including their benefits in Web applications. The article illustrates how to incorporate new WebSphere Portlet Factory builders by describing the process of adding them to the sample music store portlet application.

Ajax overview

Web development initially consisted of authoring static Web pages, which evolved into Web pages that leverage GET and POST form actions to submit complete page content to a Web server. This evolution required that the user wait for the server to process user events and to respond with an updated page. Ajax allows the user to send and receive portions of data from a Web page to the server asynchronously. The browser can respond to user events and update portions of a page with server-based data without the need to perform a full page refresh using a round trip to a remote Web server. Performance improves, and users can execute other page operations, eliminating the need to wait for a pending page update.

Ajax leverages several existing Web-based technologies:

• DHTML
• JavaScript
• XML
• XSL
• Document Object Model (DOM)

Taken together, the component technologies do not offer anything that has not been available for some time. Ajax differentiates itself from the collection of these components by aggregating them with a feature provided by the client-side DOM known as the XMLHttpRequest. WebSphere Portlet Factory V6.0.1 simplifies the addition of these features to WebSphere applications by adding new Ajax- and Dojo-based builders.

Back to top

Dojo overview

Implementing Ajax in Web pages requires you to write JavaScript code. JavaScript has always been plagued with issues such as inconsistent browser support. New frameworks have emerged to address this limitation. One of these is the Dojo open-source JavaScript toolkit.

Dojo is a set of powerful JavaScript libraries that provide a simple-to-use API that lets you implement a plethora of features more easily. Dojo frees you from writing more common JavaScript functions by providing pluggable JavaScript libraries geared toward repeating tasks such as event handling. Dojo also overcomes some of the inconsistent support of Ajax by various browsers as well as the memory leaks that plague JavaScript. Additionally, Dojo supports the XMLHttpRequest mechanism so that you do not deal with it directly. Dojo also provides packages for string and Document Object Model manipulation, drag-and-drop support, and complex data structures such as lists, queues, and stacks.

Back to top

Sample application overview

Ajax builders This article describes the following Ajax builders introduced by WebSphere Portlet Factory V6.0.1: Ajax Region builder Ajax Type-Ahead builder Ajax Highlighter builder

The Music Store application consists of the following components:

Albums Listing portlet

This portlet gives the user an Album List page view and a Search Album Catalog page view. The Album List page view displays either the entire music catalog or the results of a search by title or artist. The Album List page's Image column acts as a Dojo Drag and Drop Source. The Albums Listing's portlet appears as shown in figure 1.

The Albums Listing portlet also provides a Search Albums Catalog page view. Its Search Value edit field supports Ajax type-ahead using data appropriate to the selected Search By criteria as shown in figure 2.

Albums Cart portlet

This portlet consists of a single page view that provides a Dojo Drag and Drop Target. This portlet accumulates a list of the albums that are dragged onto it from the Albums Listing portlet. It also dynamically generates a Dojo Inline Editor control for each album displayed. This control can be used to remove the related album from the cart without the need to refresh the portlet page. This portlet also generates a running display of the total cost of the albums added to it as shown in figure 3.

Back to top

Creating the sample application

Dojo builders This article describes the use of the following Dojo builders included with WebSphere Portlet Factory V6.0.1: Dojo Drag Source builder Dojo Drag Target builder Dojo Inline Edit builder Dojo Tool Tip builder

Next, you put the various Ajax- and Dojo-based builders to use through the sample portlet application. This application consists of two portlets and is based on a music store motif. A service provider model is also defined to provide data to the two consumer portlets.

Creating the WebSphere Portlet Factory project

WebSphere Portlet Factory V6.0.1 supports these development IDEs:

• IBM Rational Application Developer V6 or V7
• Eclipse 3.1 or higher

To create the music store project, follow these steps:

1. Choose Window - Open Perspective - Other from the Eclipse or Rational Application Developer menu.
2. Select the WebSphere Portlet Factory perspective from the list in the Select Perspective dialog box.
3. Choose File - New - WebSphere Portlet Factory Project after you have opened the WebSphere Portlet Factory perspective.
4. You are prompted for a project name, and then you are asked to select from a list of feature sets to include in your project. This application requires the Dojo Extension feature selection as shown in figure 4.
   
   
   Figure 4. Adding Dojo Ajax Extension support
   
   
   
5. Next, you are prompted for a deployment configuration. Enter the details relevant to your testing environment. Select the Auto Deploy option if you want to launch your development changes immediately on a server.
6. As the New Project wizard processes your request, you see a prompt that asks the following:
   
   Would you like to add the following jars from the Feature Set to the project Java build path?
WEB-INF/work/lib/dojo_builder.jar
WEB-INF/work/lib/dojo_builders_nl1.jar
Click Yes.


Service providers

The first model defined by this project is the MusicStoreProvider, which defines a set of artists, albums, and song titles that are queried through its published service operations by the consumer portlets to retrieve data relevant to the various portlet user interface elements. Each service operation is associated with the Service Definition builder and maps to either an Action List or Method builder to return data requested by the Music Store consumer portlets. The data returned by each service operation originates from Variable builders, is self-contained within the provider model, and is read only. There are no Dojo- or Ajax-based builders defined in the MusicStoreProvider model. The following is a list of service operations defined by the MusicStoreProvider model as well as a brief description of their intended purposes.

• getAlbumsList. The getAlbumsList service operation returns a list of albums based on supplied search criteria. This operation takes two arguments, searchParameter and searchValue. The searchParameter argument defines whether a search is based on an artist or an album title. The searchValue argument identifies the value to search for within the searchParameter field data. If both the arguments are null, this method returns the entire album listing.
• getTracksForAlbum. This service operation, when called, invokes the getTracksForAlbum action list to return a list of tracks for a given album.
• getAlbumDetails. This service operation, when called, returns a set of attributes for a given album, such as title, price, genre, and more. This service operation is used by the Albums Cart portlet to add the details of an album to the cart.
• getSearchValues. This service operation is called by the Albums List portlet to obtain a list of artists or a list of titles to search. It calls the getSearchValues Method builder and accepts one input identifying whether to search for titles or artists. The results of this operation are used to populate the type-ahead values for the Ajax TypeAhead builder.

Service consumers

The music store requires the creation of two service consumer portlets: an Albums Listing portlet and an Albums Cart portlet. The following is a description of each:

• Albums Listing portlet. This portlet provides a listing of the albums. It displays either the complete album listing or the results of a search by either title or artist.
• Albums Cart portlet. This portlet implements the albums cart functionality used to accumulate a list of albums to buy.

Creating the Albums Listing portlet

To create the Albums Listing model, follow these steps:

1. Choose File - New - WebSphere Portlet Factory Model. Select the WebSphere Portlet Factory Project created previously to associate each model with that project. Select an empty model for each, and click Next. See figure 5.
   
   
   Figure 5. Creating an empty model
   
   
   
2. You are prompted to select a WebSphere Portlet Factory project to associate with the new model. Select the project you previously created, and click the Next button.
3. Add a Service Consumer builder to the model to access the services created by the MusicStoreProvider model. Use these settings:
   
   
   • In the Provider Model field, enter musicstore/data/MusicStoreProvider.
   • Select the "Add All Provider Operations" option.
   • Click the Apply button on the builder.
4. Next, add the Portlet Adapter builder to add portlet support to the model. The Portlet Title builder input defines the name of the portlet in the portal server. See figure 6.
   
   
   Figure 6. Portlet Adapter builder adds support for deployment to a portal
   
   
   
5. Add an Action List builder as shown in figure 7 and set the Name builder input to main. This is the first builder called when the portlet runs within a page. You add the Actions builder input for main in subsequent steps.
   
   
   Figure 7. Albums Listing portlet's main action list
   
   
   

Creating the Albums List page

To create the Albums List page, follow these steps:

1. Add a Page builder to the Albums Listing portlet, and call it albumsListPage.
2. Paste the HTML in listing 1 into the Page Contents builder input.

<html>
   <span name="stylesheet"></span>
    <body>
        <!-- As a best practice, change the form name to a unique name -->
        <form name="myForm" method="post">
            <div align="center">
            		<span name="namedTag" style="font:12pt Arial;
            		font-weight: bold;color: #336699;">Albums Catalog</span>
               		<span name="albumnsList"></span>
            		<br>
            		<span name="searchButton" /><span name="completeListing" />
            </div>
        </form>
    </body>
</html>

3. Add another Action List builder named getAlbumListing. This action makes a call to the service provider to obtain an album listing. The getAlbumsList service operation returns a complete listing of albums when supplying null values to both parameters. For this action list, set the searchParameter and searchValue parameters to null and make a call to the getAlbumsList service operation. Finish the getAlbumListing's Actions builder inputs with a call to the albumsListPage to render the results. These settings appear as follows:
   
   
   • Under Properties, in the Name field, getAlbumListing
   • Under Arguments, in the Return Type field, Object, and in the Actions field, the following entries under ActionList:
     Assignment!Variables/ServiceConsumerGetAlbumsListInputs/arguments/searchParameter=
     Assignment!Variables/ServiceConsumerGetAlbumsListInputs/arguments/searchValue=
     DataServices/ServiceConsumer/getAlbumList
     albumsListPage
4. Click OK, or apply to the getAlbumListing Action List builder.
5. After adding the getAlbumListing Action List builder to the model, close and reopen the main Action List builder created previously and add a call to the getAlbumListing action list in the main Actions builder input. Enter these settings:
   
   
   • In the Name field, enter main.
   • In the Return Type field, enter Object.
   • In the Actions field, under ActionList, enter getAlbumListing.
6. Add a Data Page builder call to display the results of the getAlbumsList service operation. This governs both the initial display of all albums and the results of a search of albums by title or artist. Configure the Data Page builder call to write its data to the albumList span tag of the albumListPage you created earlier. This builder renders the MusicLibrary variable that is populated by the call to the getAlbumsList service operation. See figure 8.
   
   
   Figure 8. Data Page builder inputs for albumsListPage
   
   
   
7. Add an Image builder to determine the visual display of the left-most column of album data displayed using the previous Data Page builder. The sample application defines an image for each album. It does this using the data in the Image element of the albumListVar Variable builder. Enter these settings:
   
   
   • In the Name field, enter albumImage.
   • Under Page Location, in the Page field, enter albumsListPage.
   • Under Page Location, in the Tag field, enter Image.
   • In the Image Source field, enter ${VariablesAlbumLoopVar/Album/Image}.
   
   
   Figure 9. Image builder inputs
   
   
   
8. Next, add two Button builders to the page to provide Search Albums and Get Complete Listing functionality on the searchButton and completeListing span tags of the albumListPage, respectively. Refer to the sample code in the Download section for these builder inputs.
9. Set the Complete Listing button's Actions input to getCompleteListing using the picker. Leave the Actions input of the Search Albums Button builder blank for now. Refer to the sample code in the Download section for these builder inputs.
10. Execute the model to view the Albums List page as shown in figure 10.
    
    
    Figure 10. Albums List page output
    
    
    

Back to top

Adding Dojo Drag Source functionality

Adding Dojo drag and drop support to a portlet application consists of defining both a drag and drop source and a drag and drop target. The drag and drop source is that which is dragged from a start point. The drag and drop target receives the drop event from the drag and drop source. Typically, a message is passed from the drag and drop source to the drag and drop target in the form of an argument. The drag and drop target receives this argument and performs an action. In figure 11, the Album Catalog's Image column defines a drag and drop source that can be received and processed by the Album Cart's shopping cart image.

Dragging an album's image from the Albums Listing portlet and dropping it onto the Albums Cart's shopping cart icon adds the album to the album cart and updates the total price. The result of this action can be seen in figure 12.

To add drag support to the Albums Listing portlet, add a Dojo Drag Source builder to the Image column of the albumsListPage. This lets the graphic assigned to each album through its Image element act as an album-specific drag and drop source message. Assign it the Page and Tag builder inputs of albumsListPage and Image, respectively.

You must also specify a Drag Source Data builder input of ${Variables/AlbumLoopVar/Album/AlbumID} and a Drag Type of albumID. These builder inputs allow the drag source to specify a data-driven argument to a drop target. In this case, the Dojo Drag Source builder passes an albumID associated with the image dragged to a Dojo drop.

In the Dojo Drag Source dialog box, enter these settings:

• In the Page location field, select On Named Page and enter albumsListPage in the Page field and Image in the Tag field.
• In the Drag Source Data field, enter ${Variables/AlbumLoopVar/Album/AlbumID}.
• In the Drag Type field, enter albumID.

Dojo drop target support is added later to the Albums Cart portlet.

Adding Dojo tooltip support

WebSphere Portlet Factory's Dojo Tooltip builder provides a mouseover-based popup window. You can see this in the Albums Listing portlet when you position the mouse over an entry in the Title column. The AlbumsList page displays a Dojo Tooltip-based popup window identifying the track listing for the album over which the mouse hovers within the Album Listing's Title column as shown in figure 13.

Follow these steps to implement the Dojo-based tooltip window:

1. Add a tracksPage Page builder to the Albums Listing portlet, and supply the HTML shown in listing 2 to the Page Contents builder.

<html>
    <body>
        <!-- As a best practice, change the form name to a unique name -->
        <form name="myForm" method="post">
            <div align="center"  bgColor="#809FFF">
            	<span name="tracks"></span>
            </div>
                       
        </form>
    </body>
</html>
tracksPage HTML

2. Add a tracksPage Data Page builder. Configure this builder to display the contents of the Tracks variable produced by the GetTracksForAlbum service operation. This builder places its results in the tracks tag of the tracksPage. The settings for this builder call appear as follows:
   
   • In the Name field, enter tracksPage.
   • In the Variable field, enter Variables/ServiceConsumerGetTracksForAlbumResults/Tracks.
   • In the Page in Model field, enter tracksPage.
   • In the Page Type field, select the Infer from HTML option.
   • Select the "Make UI from Data" option.
   • In the "Location for New Tags" field, enter tracks.
3. Add a tracksDataColumnModifier Data Column Modifier builder, and enter the following builder inputs:
   
   • In the Name field, enter tracksDataColumnModifier.
   • In the Container Field field, enter [tracksPage]tracksPage/Tracks/Track.
   • In the Delete Column Style field, enter No Delete Column.
   • Select the Manage Columns option.
4. Add a showTracksListingForAlbums Action List builder.
5. Assign the builder an albumID argument of type String using the Arguments Action List builder input.
6. Add an Assignment to the Actions builder input that passes the albumID argument to the GetTracksForAlbum service input variable defined by the Service Consumer builder.
7. Add an Actions builder input to display the tracksPage Page builder.
   
   The settings for the showTracksListingForAlbums Action List builder are as follows:
   
   • In the Name field, enter showTracksListingForAlbums.
   • In the Arguments field, enter albumID as the name and String as the data type.
   • In the Return Type field, enter Object.
   • In the Actions field, enter these Action List items:
     Assignment/Variables/ServiceConsumerGetTracksForAlbumInputs/arguments/
     albumID=${Arguments/albumID}
     DataServices/ServiceConsumer/getTracksForAlbum
     tracksPage
8. Add a tracksListDojoControl Dojo Tooltip builder.
9. Set the Page Location builder inputs to modify the albumsListPage's Title tag.
10. Select a Tooltip Type builder input of type Action.
11. Set the Tooltip Action to call the showTracksListingForAlbums tool defined in step 1.
    
    The settings for the Dojo Tooltip builder are as follows:
    
    • In the Name field, enter trackListDojoControl.
    • In the Page Location section, select the On Named Tag option and enter albumsListPage in the Page field and Title in the Tag field.
    • Select the Action option for Tooltip Type.
    • In the TooltipAction field, enter showTracksListingForAlbums.
    • In the Input Mapping field, enter AlbumID as the name and
      ${Variables/AlbumLoopVar/Album/AlbumID} as the value.

NOTE: When using this builder, you have the option of selecting a Tooltip Type of Text or Action. The albumsListPage defines an Action ToolTip. The Text Tooltip Type alternately lets you display Variables, DataServices return values, MethodCall results, and more.

You now proceed to add the Search Albums page view to the Albums Listing portlet, focusing primarily on Ajax-related design artifacts. Refer to the sample code included in the Download section of this article for a complete listing.

Begin by adding a searchPage Page builder. Add the HTML in listing 3 to its Page Contents builder input.

<html>
   <span name="stylesheet"></span>
    <body>
        <!-- As a best practice, change the form name to a unique name -->
        <form name="myForm" method="post">
            <div align="center">
            	<span name="namedTag" style="font:12pt Arial;font-weight: bold;
            	color: #336699;">Search Albums Catalog</span>
            </div>            
             <div align="left">
             	<span name="searchDialog"
            		<span name="searchCriteria"></span>
             		<span style="width:100px" name="searchButton" /> 
             		<span style="width:100px" name="backButton" />
             	<span>	
            </div> 
        </form>
    </body>
</html>

Adding Ajax type-ahead support

The Ajax Type-Ahead feature lets you drill into a list of selectable values as you type. The Albums Listing portlet leverages this behavior in the Search Value edit field. The Music Store application allows the user to search by artist or title. The Ajax Type-Ahead feature's type-ahead data is based on the selected search by criteria. As you type into the Search Value field, a list box appears that uses the typing in the Search Value field to drill down and filter into a sorted list of known values. In figure 14, the Ajax Type-Ahead builder suggests matches for a search by artists beginning with E.

The Ajax Type-Ahead builder operates on a span tag within an HTML page. It requires that you specify a Lookup Table Used builder input to identify the set of type-ahead data. To add Ajax type-ahead support to the Music Cart application, follow these steps:

1. Add a searchVar Variable builder to the model. This builder creates an XML variable that is used to define the search parameters.
   
   • In the Name field, enter searchVar.
   • In the Type field, enter XML.
   • In the Initial Value field, enter the following XML:
     <Search>
<SearchBy></SearchBy>
<SearchValue></SearchValue>
</Search>
2. Add a searchDataPage Data Page builder to the model. Set the Page Type builder input to Data Entry so that the user can provide search criteria. The Data Page builder in turn adds SearchBy and SearchValue tags as a result of rendering the searchVar builder on the page.
3. Add a searchByLookup Variable builder to the model. It defines a list of search criteria for the user to search by.
4. Add a SearchBy Data Field modifier, and set the Fields builder input to [searchPage]searchDataPage/Search/SearchBy. This sets the scope of the Data Field modifier to the SearchBy element defined in the first step.
5. Add an onChangeSearch HTML Event Action builder to trigger the onChangeSearchByAction Action List builder by providing these settings in the HTML Event Action dialog box:
   
   • In the Name field, enter onChangeSearch.
   • In the Page Location section, selec the On Named Tag option and enter searchPage in the Page field and SearchBy in the Tag field.
   • In the Event Name field, enter onChange.
   • In the Action Type field, enter "Submit form and invoke action."
   • In the Action field, enter onChangeSearchByAction.
   This Action List stores the user's Search By selection, invokes the Service Consumer builder to obtain a relevant list of search values from the service provider, and reloads the search page.
6. Add a searchValuesLookup Lookup Table builder to the model, and set its XML Data builder input to the results of the getSearchValues service operation's results. This variable is generated by WebSphere Portlet Factory as a result of adding the Service Consumer builder to the model. Enter the following inputs for the Lookup builder:
   
   • In the Name field, enter searchValuesLookup.
   • For the DataSource field, select XML Data.
   • In the XML Data field, enter ${Variables/ServiceConsumerGetSearchValuesResults/Rowset}.
   • For the Variable Type field, select Value Tag and Label Tag.
   • In the Value Tag field, enter Name.
   • In the Label Tag field, enter Name.

Complete adding Ajax type-ahead support by adding the SearchValue Ajax Type-Ahead builder to the application. Place the builder on the SearchValue span tag created by the Data Page Builder that you added previously. Specify the lookup table created previously as the data for the lookup table used input of the builder. The Ajax Type-Ahead builder uses the data set defined in the Lookup table to generate type-ahead suggestions. The Filter Mode builder input can be used to further refine how the type-ahead feature interacts with the type-ahead data defined for it. For this example, in the Ajax Type-Ahead dialog box, select "Show values containing data anywhere" in the drop-down list of Filter mode options. This results in type-ahead suggesting matches where the user input occurs anywhere within the lookup data. You can alternately select "Show values starting with data" in this field to narrow the suggested matches to those values that begin with the same data provided by the user. Select Show all values if you want the Type-Ahead feature to provide a complete, unfiltered list of type-ahead suggestions.

You have now completed the addition of the Ajax Type-Ahead feature.

Creating the Albums Cart portlet

The Albums Cart portlet collects a list of albums for purchase by the user. It acts as a Dojo drop target by allowing the user to add a selected album by dropping its image onto the shopping cart image. It also supports Dojo inline editing by enabling the user to update the quantity of carted albums without the need to refresh the entire page. See figure 15.

The following steps take you through the process of developing the Albums Cart portlet:

1. Begin by adding a new model to the WebSphere Portlet Factory project.
2. Add a Service Consumer builder with the same builder inputs as the Albums Listing portlet's Service Consumer builder.
3. Next, add a Portlet Adapter builder to the model with Name and Portlet Title builder inputs of AlbumsCart and Albums Cart, respectively.
4. Follow this with a cartPage Page builder. Supply the HTML in listing 4 for its Page Contents (HTML) builder input.

<html>
    <head><title>Music Online</title></head>
    <body>
        <!-- As a best practice, change the form name to a unique name -->
        <form name="myForm" method="post">
            <div align="center"><div style="font:12pt Arial;
            font-weight: bold;color: #336699;">Albums Cart</div><br>
           
            <div name="dropTag" >
                 <div name="cartImageTag" />
            </div>
           
            <span name="refreshTag">
              	<span name="cart"></span>
			 	<br>
			 	<br>
				<span name="update"></span>          	
				<br>
				<br>
				<b>Total = </b><span name="total"></span>
			</span>
							
            </div>
        </form>
    </body>
</html>
cartPage Page Contents (HTML) builder input

5. Add a main action list to the model. For now, leave the Actions builder input blank, and click OK to close the builder editor.

Add a cartImage Image builder. Supply Page and Tag builder inputs of cartPage and cartImageTag. Set the Image Source builder input to /factory/images/cart.gif.

Adding Dojo drag and drop target

To add Dojo drop support to the Albums Cart portlet, follow these steps:

1. Add the Dojo Drag and Drop Target builder to the model. This builder adds drag and drop support to a specified page tag. The drop target can then be linked to an action by supplying the Drop Action builder input as well as a Drop Type builder input to specify the type of data it is to receive. Enter the following inputs for the Dojo Drop Target builder:
   
   • Under Page Location in the Page field, enter cartPage.
   • Under Page Location in the Tag field, enter cartImageTag.
   • In the field Drop type, enter albumID.
   • Under Past Action Behaviour input section of the builder, in the field Post-Action Behavior, choose "Refresh specified page location after running action."
   • Under Location to Refresh, in the field Page, enter cartPage.
   • Under Location to Refresh, in the field Tag, enter refreshTag.
   Note that you need to create an Action List builder prior to setting the Drop Action builder input. For now, click OK to close the Dojo Drop Target builder.
2. Add the refreshCart Action List builder to the Cart model. The refreshCart action receives album details from the service provider. It then adds the album to the cart, updates the total price of all the albums currently in the cart, and refreshes the cart page.
3. Add an albumID argument to receive the albumID passed to the drop target by the drag source.
4. Set the Return Type builder input to Object.
5. Enter these builder inputs in the refreshCart Action List Dialog box:
   
   • In the Name field, enter refreshCart.
   • In the Arguments field, enter albumID as the name and String as the data type.
   • In the Return Type field, enter Object.
6. In the Actions field, enter these Action List items:
   
   • Assignment/Variables/ServiceConsumerGetAlbumDetailsInputs
   • /arguments/albumID=${Arguments/albumID}
   • DataServices/ServiceConsumer/getAlbumDetails
   • addAlbumToCartCallCopy
   • calculateTotal
   • cartPage
7. Open the Dojo Drop Target builder you created previously, and specify refreshCart as the Drop Action builder input.

Adding Dojo inline editing functionality

Dojo inline editing allows the user of the Albums Cart portlet to update the quantity of carted albums and recalculate their total cost. To add this support to the Cart portlet, follow these steps:

1. Add a calculateTotal Method builder. Add the code from the sample code, available in the Download section of this article, to the Method Body builder input.
2. Add an onQuantityUpdate Action List builder. Add calls to calculateTotal Method builder and the cartPage Page builder to redisplay the results.
   
   • In the field Name, enter onQuantityUpdate.
   • In the field Actions, enter two Actions, calculateTotal and cartPage.
3. Add a Dojo Inline Edit builder to the Cart model. Enter the following builder inputs in the Dojo Inline Edit dialog box:
   
   • In the Name field, enter QuantityDojoInlineEdit.
   • In the Fields field, enter [cartPage]cartDataPage/MusicLibrary/Album/Library in the list of fields to be modified.
   • Select the Submit Form option.
   • In the Action field, enter onQuantityUpdate.
   • In the Post-Action Behavior field, select "Refresh specified page location after running action" from the drop-down list.
   • In the Location to Refresh field, select the On Named Tag option, select cartPage from the drop-down list in the Page field, and select refreshTag from the drop-down list in the Tag field.

This completes the Dojo inline edit functionality.

The following steps add support to update the Albums Cart due to changes in quantity or change as a result of a deletion.

1. Begin the Cart update by adding two Transform Filter builders. The first Transform Filter, updateForDeletedItems, is called to filter out the albums checked for deletion from the cartListVar Variable.
   
   • In the Name field, enter updateForDeletedItems.
   • In the Variable field, enter cartListVar.
   • In the Element to Filter, enter MusicLibrary/Album.
   • In the Target Variable, enter cartListVar.
   • For Filter Behaviour input, select Filter Out Matching.
   • For Filter By input:
     For Element, enter Album/Remove.
     For Operator, select = sign.
     For Operand, enter 1.
     For Compare Method, select Number.
2. Next, add an updateForQuantity Transform Filter builder. This builder filters out any albums from the MusicLibrary Variable associated with the Albums Cart with a Quantity of zero. The settings for this builder are as follows:
   
   • In the Name field, enter updateForQuantity.
   • In the Variable field, enter cartListVar.
   • In the Element to Filter field, enter MusicLibrary/Album.
   • In the Target Variable field, enter cartListVar.
   • In the Filter By field, enter Album/quantity as the element, = as the operator, 0 as the operand, and number as the compare method.
3. Create an updateCart action list to link together the sequence of actions necessary to refresh the cart display in response to various user events. The builder inputs for the updateCart action list are as follows:
   
   • In the Name field, enter updateCart.
   • In the Return Type field, enter Object.
   • In the Actions field, enter these ActionList items:
     updateForDeletedItemsCallFilter
     updateForQuantityCallFilter
     calculateTotal
     cartPage
   Complete the Update Cart functionality by linking a button to the calls in the updateCart action list.
4. Add a Button builder to the Cart model. Set the Page Location builder inputs to the cartPage's update tag.
5. Set the Label builder input to Update Cart.
6. Configure its Action Type to "Submit form and invoke action."
7. Supply an Action builder input of updateCart.

This completes the Albums Cart portlet. Refer to the sample code in the Download section of this article to see these models in their entirety.

Back to top

Conclusion: Limitations and lessons learned

WebSphere Portlet Factory V6.0.1 gives you new Dojo and Ajax builders that let you use these technologies in model-based development. There are a few things to keep in mind when using these builders. As a simple rule, when using more than one Ajax or Dojo builder within a single model, ensure that they do not overlap in the same region on the HTML page. For example:

• If you are using a Dojo Drop Source builder, then you cannot add an Ajax Region builder to the same page if the Ajax Region builder is scoped at the page level. You can, however, add the Ajax Region builder to a span tag within the page if it in no way overlaps with the Dojo Drag Source builder.
• If you are using a Dojo Drop Target builder, then you cannot make a Dojo Tooltip builder work inside the span tag in which the Dojo Drop Target builder is placed.
• Similarly, the Ajax Region and Ajax Type-Ahead builders cannot be used within the same page region if they overlap each other. They can, however, coexist if the builders are placed on span tags that do not overlap each other.

When you add a second Ajax or Dojo builder to a span already wrapped by another such builder, the JavaScript generated by it is not refreshed to reflect the other builders' action on the same page region. This can lead to undesirable results, and most likely some Ajax or Dojo functionality will be lost. Ensure that the builders operate in their own regions and that they do not overlap regions with each other.

Back to top

Download

	Information about download methods

Resources

• Participate in the discussion forum.
  
  
• Read the developerWorks article, "Getting started with WebSphere Portlet Factory V6.0.1."
  
  
• Learn more about IBM WebSphere Portlet Factory.

About the authors

		Stephen Cooke is an Advisory I/T Specialist with over 12 years of experience helping customers with Lotus and companion products. He started programming computers on the Apple II, and has worked with a variety of platforms and programming languages since that time. Stephen joined the IBM Software Group in 2000, where he works with Lotus and WebSphere related products. In his spare time, he enjoys tennis, ping-pong, basketball, juggling, and spending time with his family.

		Abhishek Singh is a Senior I/T Specialist with IBM Software Services for Lotus and has worked with IBM WebSphere Portal products since 2003. He specializes in WebSphere Portlet Factory and design and development of enterprise J2EE applications. His experience includes designing and developing software products, service-oriented architecture, information systems, telecom applications, and client/server applications.

Rate this page

Please take a moment to complete this form to help us better serve you. Did the information help you to achieve your goal? Yes No Don't know   Please provide us with comments to help improve this page:   How useful is the information? 1 2 3 4 5 Not useful Extremely useful

Share this.... Digg this story del.icio.us Slashdot it!

Back to top