-C H A P T E R

C H A P T E R 19

Tutorial--Section 4.4
Add Results Listing to the Google Search Page

This chapter describes how to create a TiledView pagelet component to display a list of results from a Web service model. The TiledView will be added to an existing page component.

Task 4: Create a TiledView Pagelet

Add a TiledView

1. Select the main module, and click the Add Pagelet button on the Sun ONE Application Framework toolbar.

This figure shows the Add Pagelet button on the Sun ONE Application Framework toolbar.

The Select View Type panel displays.

This figure shows the Select View Type panel.

2. Enter SearchResultsPagelet in the Name field (to replace <default>).

3. Select Basic Tiled View from the pagelet component type list.

4. Click Next.

The Associate JSP panel displays.

This figure shows the Associate JSP panel.

A matching JSP is not be created for this pagelet component. This pagelet component's JSP tags and content will automatically be added directly to the parent page component's JSP page.

Note - The question is whether to create a JSP for a pagelet component or not. There are pros and cons to both possibilities. The deciding factor is how the pagelet component will be reused on the JSP side. If the pagelet is meant to be rendered the same regardless of what page (or another pagelet) parents it, then you should create a JSP for the pagelet. This single JSP pagelet file will be included (JSP file include directive) in every parenting page and pagelet JSP that requires it. Therefore, any change made to the JSP pagelet file will be reflected wherever it was included.

However, if the pagelet requires the flexibility of being rendered in a different way for various parenting JSP pages and pagelets, the JSP pagelet content must be inlined and customized in each of its parenting JSP page or pagelet files.

The nuances of these techniques might not be clear to you right away, but do not be concerned. As you become more skilled with JSPs and the Sun ONE Application Framework, you will begin to fully understand the flexibility and power of the reusability of the Sun ONE Application Framework page and pagelet components.

For more information, read the notes that are included on this wizard panel, and refer to the Sun ONE Application Framework Developer's Guide and the Sun ONE Application Framework Component Developer's guide.

5. Click Next.

The Model Associations panel displays.

This figure shows the Model Associations panel.

6. Expand Current Application Components to expose jatotutorial/main.

7. Select GoogleSearchModel.

8. Click Add.

9. Click Next.

The Bind Display Fields panel displays.

This figure shows the Bind Display Fields panel.

10. Expand the doGoogleSearch node.

11. Expand the Returns node.

12. Expand the resultElements node.

13. Add the following three return parameters as Static text fields:

title

summary

14. Click Finish.

You have created the SearchResultsPagelet TiledView with three fields that are bound to some return parameters in the GoogleSearchModel.

The figure on the left shows the SearchResultsPagelet TiledView. The figure on the right shows the code.

15. Rename the fields to have shorter, simpler names.

The following table shows the longer field names in the left column, and the shorter names in the right column.

doGoogleSearchRESULTSTitle	to title
doGoogleSearchRESULTSURL	to url
doGoogleSearchRESULTSSummary	to summary

Configure the TiledView Pagelet Component

You need to set three properties for a TiledView pagelet component.

Properties are filled in with the necessary values in the figure shown below.

This figure shows the properties for a TiledView pagelet component.

1. Select the SearchResultsPagelet TiledView.

2. In the property sheet, set the Primary Model Reference by selecting googleSearchModel from the drop down list.

The primary model is the model that controls the iteration of the TiledView when it is being displayed.

3. Set the Max Display Tiles to 5.

This will limit the number of displayed results to 5 items.

A value of -1 (the default) means retrieve/display all possible results.

4. Set the Primary Model Dataset Name property to be doGoogleSearch.RESULT:/resultElements.

Getting the Correct Primary Model Dataset Name

A TiledView requires a primary model of type DatasetModel so that the view will have a domain for the tiles. In the case that the primary model is a MultiDatasetModel, you might optionally specify the Primary Model Dataset Name so that the TiledView will automatically set the CurrentDatasetName on the MultiDatasetModel in both the display and submit cycle.

It is not imperative that you fully understand this concept, yet. To put it into simpler terms, a Web service model can have more than one result set. The Primary Model Dataset Name property just lets you specify which one to use, by default, for a particular TiledView.

The Primary Model Dataset Name value is provided for you in this tutorial, but how would you know what this value should be if you were to do this on your own? If you know Web services well enough, you probably know this answer without a problem. You worst enemy would be a typo causing some nasty runtime exceptions.

Currently, the Application Framework tools do not have a direct way to set this value by browsing the Web service, and selecting a key path. But there is a one-off Web service browsing technique for getting to this value so that you can copy it, then paste it into the property.

Start by selecting the GoogleSearchModel in your application.

1. Right click the model, and select Browse/Add Object Field Bindings.

This figure shows the Browse/Add Object Field Bindings option in the GoogleSearchModel.

The Web Service Field Bindings editor is launched.

This figure shows Web Service Field Bindings editor.

2. Navigate down the operation path where the fields in the TiledView are bound.

This figure shows the operation path where the fields in the TiledView are bound.

3. Select the parent node of the fields: resultElements

Notice the bold-faced Selected Dataset value at the bottom of this editor: doGoogleSearch.RESULT:/resultElements.

Although it does not appear to be selectable, you can use your mouse to click/drag select it.

This figure shows the selectable Selected Dataset value at the bottom of the editor.

4. Highlight it and press Ctrl-C to copy the value to the buffer.

5. You can now Cancel out of this editor.

Do not click OK, as doing so adds a field to your Web service model. Although there is no harm in this, you do not need the field.

6. Select the SearchResultsPagelet TiledView node, and paste the value into its Primary Model Dataset Name property.

Add the Pagelet to a Page

A pagelet cannot display without the help of a root view. A page (a ViewBean) is a root view. A root view is a container view that can contain other views, but cannot be contained by another container view. All view hierarchies must have a root view. How many levels of views below the root view is completely arbitrary and up to the developer.

This is much like PC filesytems with drives and directories. A drive (analogous to a page) is always at the top of every absolute path (the root), and there are never any drives that are not at the top level of the path.

Directories (analogous to pagelets) must be contained under drives or other directories. These directories can be nested arbitrarily deep under a drive.

Files (analogous to display fields) must be contained by drives or directories. Files cannot contain other files, directories, or drives.

1. Expand the GoogleSearchPage node.

2. Right-click the GoogleSearchPage's Visual Components node, and select Add Visual Component.

This launches the Component Browser.

This figure shows the Component Browser dialog.

3. Expand the Current Application Components node.

4. Expand jatotutorial.

5. Expand the main node.

6. Select the SearchResultsPagelet TiledView component.

7. Click OK.

This figure shows the selected SearchResultsPagelet TiledView component.

The SearchResultsPagelet TiledView is added as a visual component under the GoogleSearchPage just like the other visual components. Notice that the pagelet does not have a JSP itself. The pagelet and the other visual components that are contained by the pagelet will have tags added to the parenting page component's JSP page. A pagelet component can be reused by multiple page components, but this is a topic outside the scope of this tutorial.

Formatting the JSP

1. Open the JSP by double clicking the GoogleSearchPage JSP page node.

At the bottom of the JSP, the TiledView pagelet and contained display field tags have been inserted, but without any formatting.

You can add all the HTML markup you want, but the display field tags that belong to the SearchResultsPagelet TiledView must be nested inside of the jato:tiledView tags.

2. Feel free to be creative with the HTML formatting or use the following content to get you started.

Note - All of this content is inserted just before the ending JATO form tag (</jato:form>), leaving the current content untouched. All of the content between the body tags is being presented here. However, only the bold code needs to be added.

<body>

<jato:form name="GoogleSearch" method="post">

<jato:hidden name="key"/>

<h1>Google Search</h1>

<h2>Search Criteria</h2>

Search for: <jato:textField name="queryString"/><br>

Start: <jato:textField name="start"/><br>

Max results: <jato:textField name="max"/><br>

<jato:checkbox name="filter" label="Filter?"/><br>

<jato:checkbox name="safeSearch" label="Safe Search?"/><br>

Restrict: <jato:textField name="restrict"/><br>

<jato:button name="search"/>

<hr size="3">

<h2>Results</h2>

Search Time: <jato:text name="searchTime"/><br>

<jato:text name="startIndex"/> to <jato:text name="endIndex"/>

of <jato:text name="estTotal"/>

<jato:tiledView name="searchResultsPagelet1">

<hr size="1">

Title: <jato:text name="title" escape="false"/><br>

<a href="<jato:text name='url'/>" target="_blank">

  <jato:text name="url"/>

</a><br>

Summary: <jato:text name="summary" escape="false"/><br>

<br>

</jato:tiledView>

</jato:form>

</body>

A few things above need to be explained:

First, take a look at the escape attributes for the title and summary field tags. The default is true, which means escape all special characters. This means that any HTML markup that is returned in the value of this field will be visible to the end user. This Web service places bold tags (<b>) around any words that match the query string that was entered by the end user. So, by specifying escape=false, you are telling this tag that you want the markup to be rendered as HTML markup, not displayed to the end user. Experiment with this attribute by making one tag false and the other true to see the difference.

Second, notice that there are two occurrences of the tag that represents the url field. A simple copy/paste of the tag allows you to display the same dynamic data many times. In this case, the first instance of the tag will populate the href attribute of the anchor tag (<a href="...").

Notice also that the name attribute of this instance of the url field tag uses single quotes. This is because this tag is contained inside of double quotes for the href attribute value. Using double quotes nested inside of double quotes should render perfectly fine at runtime, but many HTML editors will indicate an error condition for this case. Using the single quotes inside the double quotes should remedy these situations.

The second instance of the url field's tag is used to display it as the link text to the user.

Everything between the two jato:tiledView tags will appear once per row of data that is returned (five times in this example).