Portal Guide

CHAPTER 11

Developing a Wireless Application

This chapter describes how to build exteNd Director portal applications that support wireless devices. It contains the following sections:

About wireless applications

exteNd Director allows you to easily extend your applications to the constantly expanding variety of devices used by the mobile community, such as handheld computers and cellular telephones. Any portlet that produces XML output can use exteNd Director's wireless capabilities to produce output suitable for wireless devices. You do not need to modify portlet output according to the size or type of display when implementing a portlet class.

The process of enabling applications for wireless devices consists of two steps: device-specific rendering and device-specific pagination. Although the steps are intended to work together, either one can be used separately. For example, a search engine can use device-specific pagination to present a specific number of hits per page for Web browsers on personal computers as well as wireless devices.

Device-specific rendering

You can designate any XML portlet in your exteNd Director application as wireless-enabled, which allows the Portal Aggregator to automatically identify wireless client devices and render the portlet's XML output in device-specific formats such as WML, cHTML, or Web Clipping.

The Portal uses a list of profiles for various devices that is stored in the portal's resource set. Updates to the list will be made available for download from the Novell Web site as new devices and formats appear on the market.

Application content that is already small enough to fit on a single page may require nothing more than rendering in the appropriate device-specific format. In other words, reducing the width of a page by increasing the length may or may not be acceptable. You must decide how much vertical scrolling (if any) you consider acceptable for a single page.

Device-specific pagination

Some portlet content is too large to fit on a single page. Thus, you can designate any XML portlet in your exteNd Director application for device-specific pagination, which slices the portlet's XML output into smaller blocks and adds navigational aids such as tables of contents and previous-next buttons.

Using a graphical editor integrated with development environment, you can drag and drop pieces of a sample portlet content file into a data definition that models both layout and navigation. As you work, you can instantaneously preview the output produced by your data definition.

At runtime, the device transcoding engine applies the data definition to the portlet's output before sending it to the Portal Aggregator.

Sample portlet

Your exteNd Director software includes a sample wireless-enabled portlet named StockQuotePortlet that uses device-specific rendering. You can use this portlet to begin learning about how to provide wireless support in your applications.

Creating a wireless-enabled portlet

You can create a wireless-enabled portlet using the Portlet Wizard, which does much of the work for you.

Procedure To create a new wireless portlet:

Invoke the Portlet Wizard, as described in the section on using the Portlet Wizard.
Under Content Types, select XML and WML.
If you already have a device transcoding data definition for the portlet, specify it here. Otherwise, click Finish and turn to Creating a device transcoding data definition.

Wireless-enabling an existing portlet

To wireless-enable an existing portlet, you will need to modify and/or create several files as described in the following procedures.

Procedure To modify the portlet source file:

Edit the portlet source file.
In the doView() method, set the MIME type to MIME_TYPE_XML, as shown below:
```
  response.setContentType(com.novell.afw.portlet.api.EbiPortletConstants.MIME_TYPE_XML);
```
NOTE: If you want to develop a wireless portlet that supports transcoding, you would need to set the MIME type to MIME_TYPE_DEVICE_PROFILING.

Procedure To modify the portlet descriptor:

Open the portlet descriptor.

In the style section, enter the name of the Data Definition file, if you plan to support transcoding. The data definition file does not have to exist at this point.

  <style>
   <name>MyPortletDefault</name>
   <display-name>MyPortlet Default Style</display-name>
   <user-agent>
    <device-name>Generic_HTML</device-name>
    <file-name>
     $RESOURCE_SET$/portal-style/MyPortlet_HTML.xsl
    </file-name>
   </user-agent>
   <user-agent>
    <device-name>Generic_WML</device-name>
    <file-name>
     $RESOURCE_SET$/portal-style/MyPortlet_WML.xsl
    </file-name>
   </user-agent>
   <data-definition>
    $RESOURCE_SET$/portal-data-definition/PhoneList
   </data-definition>
      </style>

In the style section, examine the selected styles. If the portlet already has a portal style, proceed to To modify the portal style descriptor:. Otherwise, choose one of the following:
- Select GenericStyle and proceed to Creating a device transcoding data definition.
- Create a new portal style descriptor.
In the auto-register section, add the category Wireless.
```
  <auto-register enabled="true">
    <category>Wireless</category>
  </auto-register>
```
You can also set the category in the Portlet Management section of the DAC.
If you choose to create a new portal style descriptor at this point, invoke the Portal Style Descriptor Wizard.
Name the descriptor and proceed to To modify the portal style descriptor:.

Procedure To modify the portal style descriptor:

Open the descriptor and click the User Agents tab.
If there is not already a user agent named Generic_WML, click the Add button.
A user agent specifies how the portal style is rendered for a particular user environment by mapping a device profile to an XSL style sheet.

Set the Device Name (<device-name>) to Generic_WML. The device name is the name of a device profile that defines the user environment.

Set the Data Definition (<dp-file-name>) to an XSL style sheet.

NOTE: The Data Definition column in the portal style descriptor GUI should not be confused with a device transcoding data definition.

If you do not have a style sheet for the portlet, use one of the generic style sheets provided in the portal-style directory such as Generic_WML.xsl.
```
  <user-agent>
      <device-name>Generic_WML</device-name>
      <dp-file-name>Generic_WML.xsl</dp-file-name>
  </user-agent>
```
For more information about device profiles, see Using the device profile editor.

Using the Wireless Layout Manager

The Wireless Layout Manager allows you to define a wireless profile. Using a Web browser, you can select from the available wireless-enabled portlets and set the order in which they are displayed. The list contains portlets that have the category Wireless.

Procedure To define a wireless profile:

Open the Portal Personalizer, scroll to the Portal Wireless Layout section and click Edit Wireless Layout.

NOTE: The Edit Wireless Layout link is not visible unless the Show Wireless Layout preference for the Personalizer portlet is set to True. To set this preference, you need to modify the portlet registration for the Personalize portlet in the DAC.

The Wireless Layout Manager opens in your browser.
In the Wireless Layout Manager, select any available portlet and click Add Portlet.
To see the wireless portlets in action, click Save Portlets, go to MyPortal, and click MyWirelessProfile.

Using the device profile editor

exteNd Director provides a graphical editor in development environment for creating or editing device profiles.

Procedure To start the device profile editor:

Double-click an existing device profile.
Select File>New>Portal>Device Definition (Wireless).

Procedure To use the device profile editor:

The following specification describes the fields in the device profile editor:

http://www1.wapforum.org/tech/terms.asp?doc=WAP-248-UAProf-20011020-a.pdf

NOTE: To access the specification, you first need to logon to the site.

There is a slight difference between the WAP specification and the exteNd Director editor—because Wapforum uses RDF to describe information and exteNd Director uses descriptor tags. This makes it possible to use a W3C schema for tag-completion in the XML source view.

Creating a device transcoding data definition

About transcoding data definitions

A transcoding data definition is an XML file that identifies certain tags in portlet output that can be used to specify how to slice the output data and add navigational aids. The first step is to capture a representative sample of portlet output, as described in Creating a reference file.

Once you have an output sample to work from, consider it to be a table with columns and rows. The next step is to identify which tag is the row separator. When you have defined the row separator, you can map the output data onto the following objects:

Object	Description
List block	A view that includes all rows
Content block	A view that includes only one row
Element	A column
Link	Connects a list block to a content block

Creating a reference file

To create a reference file, you need to capture a sample of your actual XML portlet output in a file. Any XML-based portlet can print its XML to the console by doing the following:

  // Create the XML Document
  Document newDoc = EboXmlHelper.getNewDocument();
  
  // Add elements to the document
  ...
  
  // Print the document to the console
  com.sssw.fw.util.EboXmlHelper.printDOMTree(newDoc);

Save the text file in the portal-data-definition folder using a name that does not conflict with the actual data definition file. For example, some XML output from the PhoneList portlet is shown below. For convenience, you can copy this output and paste it into a text file named PhoneListReference.xml.

  <?xml version="1.0"?>
  <phonelist compInstance="a63974dcac7e4f28bd2c49ab7b1921d2"
   compid="PhoneList" post-url=
   "http://localhost/ExpressPortal/portal/portlet/PhoneListPortlet">
   <results querystring="c">
    <employee>
     <first-name>Samuel</first-name>
     <last-name>Craddock</last-name>
     <phone-number>(617) 343-6505</phone-number>
     <email>scraddock@silverdemo.com</email>
    </employee>
    <employee>
     <first-name>John</first-name>
     <last-name>Chester</last-name>
     <phone-number>(617) 343-6506</phone-number>
     <email>jchester@silverdemo.com</email>
    </employee>
    <employee>
     <first-name>Lynn</first-name>
     <last-name>Campbell</last-name>
     <phone-number>(617) 343-6507</phone-number>
     <email>lcampbell@silverdemo.com</email>
    </employee>
   </results>
  </phonelist>

Creating a data definition file

exteNd Director includes a wizard for creating transcoding data definition files.

In development environment, select File>New from the menu and select the Portal tab.
Select Transcoding Definition (Wireless) and click OK.
Name your transcoding definition file, specify which resource set to add the files to (if necessary), and click Next.
Select your reference file. The wizard automatically opens the file and displays the XML tag structure.
Select the row separator. If you are using the sample portlet reference file (PhoneListReference.xml), select Employee.
Click Finish.

Editing a data definition file

This section uses the sample portlet data definition file PhoneList.xml and reference file (PhoneListReference.xml) to illustrate the procedure.

Procedure To open a reference file:

In the data definition editor, select the Definition tab. It has two panes: Reference and Definition.
Open a reference document (unless one is already open). Right-click the Reference pane and select Open a reference file.

NOTE: The sample portlet reference file is named PhoneListReference.xml.

The Reference Pane displays the structure of the data using a tree view. You can click plus (+) to expand and minus (-) to collapse branches of the view.

Procedure To define a row separator:

If you have already defined a row separator (as described in Creating a data definition file), skip this procedure.

Drag a tag from the Reference Pane to the empty block in the Definition Pane.

Procedure To create blocks:

Select any item in the Definition Pane.
Right-click and select Add Block.

NOTE: If you are using the sample portlet reference file, create two blocks: a List block named employeeList and a Content block named employeeDetails
Name the new block and set the type to List or Content.
You can specify a Style to override the default style for this block only.

NOTE: Click the small triangle () to the right of the block name to keep the block open when you move the cursor to another object. The triangle changes color and rotates to point downward () to indicate that the block is locked open. By default, the editor closes objects (displays only the name of the object) when you move the cursor elsewhere.

Procedure To create elements:

Select an element in the Reference Pane and drag it onto a block in the Definition Pane.

NOTE: If you are using the sample portlet reference file, add the following elements:To employeeList: firstName, lastNameTo employeeDetails: firstName, phoneNumber, email
Name the new element.
The Type field provides a way to pass user defined information to the style sheet.
The XPath expr field is an expression in XPath (XML Path Language) for addressing parts of an XML document. You can use this field to remap the element.

For more information about XPath, see the language specification (http://www.w3.org/TR/xpath).

Procedure To create a link:

Select any item in the Definition Pane.
Right-click and select Add Link.

NOTE: If you are using the sample portlet reference file, set:From block to employeeListFrom element to firstNameTo block to employeeDetails
Set the From block attribute to a List block.
Set the From element attribute to an element in the List block.
Set the To block attribute to a Content block.

Testing a data definition

The Test View allows you to view the output produced by the transcoding definition you just created.

Procedure To set up the test view:

In the data definition editor, select the Test definition tab. It has three panes: Setup, Navigation, and Result.
In the Setup Pane, select one of the available user agents from the dropdown list. The list contains all of the registered device types in the portal.

NOTE: If you are using the sample portlet data definition, set the User-agent to Generic_WML.
Select one of the available styles from the dropdown list. The list contains all of the styles that support the selected user agent.

NOTE: If you are using the sample portlet data definition, set the Style to PhoneListStyle.xml.

Procedure To execute the test:

When you have made your selections, click GO.
Examine the Navigation Pane. Click plus (+) to expand and minus (-) to collapse branches of the view.
Click any item to see the transcoding engine output in the Result Pane.

TIP: For a graphical view of the rendered data, set up a Wireless Profile (as described in Using the Wireless Layout Manager) and add the PhoneList portlet to your profile.