Creating Layouts, Themes, Image components - IBM Layouts, Themes, Image components ... Mozilla Firefox browser with User ... In the design view of the theme editor, add a new Selector

© IBM Corporation 2010

Owner: IBM Version: 1.0

Page1 of 35

IBM Software Group

IBM Mobile Portal Accelerator

Using MCS Components

Creating Layouts, Themes, Image components

Version: 1.0

Author:

Krishna C Kumar,

IBM MPA Development Team,

India Software Labs.



Page2 of 35

TABLE OF CONTENTS

1. TARGET AUDIENCE ............................................................................... 3

2. SOFTWARE/TOOLS REQUIRED ............................................................ 4

3. BACKGROUND ........................................................................................ 5

4. USING MCS COMPONENTS ................................................................... 6

4.1 USING MCS COMPONENTS IN MOBILE PORTLETS ........................................................................... 6 4.1.1 Add grids to the MCS Layout .................................................................................................. 6 4.1.2 Styling a mobile portlet with theme component .....................................................................12 4.1.3 Using Image Component .......................................................................................................17 4.1.4 Configuring the a single image Component for multiple image formats ...............................21 4.1.5 Using Spatial Iterator ............................................................................................................27 4.1.6 Using Regions in Layouts ......................................................................................................29 4.1.7 Using CSS in JSP and Themes ...............................................................................................31 4.1.8 Differentiating Column Width & Pane Width In Layouts ......................................................32

5. REFERENCE .......................................................................................... 35



Page3 of 35

1. TARGET AUDIENCE

The development guide document is targeted for the Mobile Portal Developers using MPA. The target audience are expected to be having the knowledge of the following

Rational Software Development Platform (RAD/RSA)

HTML/XHTML/CSS

Basic knowledge of Mobile Web User Interface



Page4 of 35

2. SOFTWARE/TOOLS REQUIRED Listed below are the tools required for performing this best practices

IBM Rational Application Developer or Rational Software Architect 7.5.2 (until 7.5.5)

IBM WebSphere Portal Server 6.1.0.1 (with necessary APARs)

IBM Mobile Portal Toolkit 6.1 (as a part of IBM MPA license)

Mozilla Firefox browser with User Agent Switcher

Device Emulators (described in the Testing section)



Page5 of 35

3. BACKGROUND

IBM Mobile Portal Accelerator (formerly IBM WebSphere® Everyplace® Mobile Portal Enable - WEMP) software is an advanced content adaptation product that helps enterprises and service providers deliver portal content to a broad range of mobile devices, providing customized mobile access to portal solutions and services via a highly navigable, personalized Web experience.

IBM Mobile Portal Accelerator (MPA) software provides an easy, cost-effective way to deliver content and applications to virtually all mobile devices. It includes out-of-the-box mobile portal samples and tools to develop portlet applications for mobile devices. Its intelligent Multi-channel Server adapts the content for each mobile device based on the specific device characteristics and capabilities, as defined in the software`s device repository. Developers can therefore "write once" and render personalized Web content quickly across over 6000 different mobile device types.

XML Device-Independent Markup Extensions (XDIME) is an abstract, device-independent markup language based on Open standards. XDIME can be processed and converted by the components of MPA, such as MCS (Multi Channel Server), into a wide variety of markup languages, such as WML 1.1, WML 1.3, XTHML Basic, XHTML-MP, HTML 3.2, HTML 4.0, and others. So that developers can just write one version XDIME-enabled source files for a wide variety of mobile devices.



Page6 of 35

4. Using MCS Components In the development activity of the Mobile portlets using the mobile portal accelerator, apart from the functionality the user experience with respect to look and feel of the Mobile portlet pages are considered very important. This can be achieved by using the proper way of using MCS components like Layouts, Themes, Image Components, etc. This article shows the basic way of creating a layouts, themes, and image components while developing the Mobile Portlets using Mobile Portal Accelerator.

4.1 Using MCS Components in Mobile Portlets

4.1.1 Add grids to the MCS Layout

A canvas is a layout area where you can position formatting objects and associate them with elements in your web content. On a PC, MCS delivers a canvas as a single web page. On smaller devices, MCS sends complex canvasses as sets of pages.

The figure shows a canvas layout, designed to display help text on a PC , as it appears in the Design page of the Layout editor.

An outer grid consists of two columns. The left column contains a another grid with three panes for sections in a table of contents, and the right column contains a single pane for topics.

When there are multiple panes are to be added to the layout, it is possible via using GRIDs. Grids can be added with any matrix type (row by column), following explains how a layout can be added with the grid of 2 X 2.



Page7 of 35

1. Click menu File > New -> Other

2. Choose MCS project items and select the layout

3. Enter the name for the layout – say “sample_layout.mlyt” (select „mcs-policies‟ for the location of the layout)



Page8 of 35

1. Click Finish. 2. Double Click the layout and it opens with the Layout Editor



Page9 of 35

3. Choose the default variant as shown in the above image and go to the design view of the layout

4. Right Click and Choose Add> Grid > N by M 5. Add the number of grid cells required as follows (here 2 x 2)

6. Following is the layout design after the grid is added.



Page10 of 35

7. Add panes to the empty grid cells. (Right click the empty cells and Add > pane)

8. Name all the panes using Format Attributes window



Page11 of 35

9. Open the XDIME/JSP (double click the jsp located under xdime directory of the portlet project from the Project Explorer)

10. Modify the XDIME jsp to include the code for the new panes added to the layout.



Page12 of 35

11. Save the project and Run on server. 12. Using the firefox useragent switcher or emulator the rendering can be verified

4.1.2 Styling a mobile portlet with theme component

A canvas is an layout area where you can position formatting objects and associate them with elements in your web content. On a PC, MCS delivers a canvas as a single web page. On smaller devices, MCS sends complex canvasses as sets of pages.

The figure shows a canvas layout, designed to display help text on a PC, as it appears in the Design page of the Layout editor.

1. After creating a simple mobile portlet project, Click menu File > New -> Other 2. Choose MCS project items and select the theme



Page13 of 35

3. Click “Next” button to provide the name of the theme component.

4. Choose the Theme Variant (select Default) and click „Next’ to add the theme component to the mobile portlet project.



Page14 of 35

5. Open the theme using the theme editor. Select the Default variant and choose the design view of the theme.

6. In the design view of the theme editor, add a new Selector by clicking the “New” button.



Page15 of 35

7. Add the markup element which needs to be syled. Say as shown below and click finish to complete the addition of the selector element

8. select the class selector added and set the syle properties

9. Style properties are similar mappings of CSS syle properties to a GUI in the theme editor. 10. Set the background color of the selector element added as “GREEN” as shown in

the figure



Page16 of 35

11. Open the XDIME/JSP and add the theme attribute to the canvas element. <canvas layoutName="/sample_layout.mlyt" theme="/styler.mthm" type="portlet">

12. Make sure the styled selector is available in the xdime jsp. For example, here

 This paragraph text is styled using theme

Of the xdime/jsp is styled by the style selector of the theme.

13. Save the project and run on the server 14. View the rendered page on the emulator or the user agent switcher



Page17 of 35

15. To add more style properties to the selector, Open the theme in the theme editor and select the selector and add new properties as shown below. (here set the font size to large) and view the output on the device emulator.

4.1.3 Using Image Component

Image component is an MCS component, which is used to specify different set of images to point to it. This image component is used in the XDIME code like the image tag used in the usual HTML markup. It is MCS engine which takes care of using appropriate image for the page requested device and render the markup according to the device browser. For example, if a device is capable of rendering the GIF image, the MCS will use the image component and its resource images and render the <img> tag for the resulting device specific markup. Following is the simple example to show the way to use image component in XDIME/JSP.



Page18 of 35

1. Add a folder called “images” to the Project under WebContent 2. Copy the images into the „images‟ created in step-1. 3. Creating a simple mobile portlet project, Click menu File > New -> Other 4. Choose MCS project items and select the Image Component

5. Click Next and provide the image component name (say „GIF‟) 6. Browse the project folder for images and Click finish. (similarly follow the same for

multiple image components)



Page19 of 35

Following screen shows on how an image component is configured.

Criteria can be configured as Default or Genrric Image or Targeted for certain group of devices.

Make sure the image URL specified is the right location of the image location.



Page20 of 35

7. Open the XDIME/JSP and add the image component name to the appropriate pane as follows.

8. Save the project and Run the project on the server 9. Render the project on the Emulator or Firefox useragent switcher.



Page21 of 35

4.1.4 Configuring the a single image Component for multiple image formats

1. Create a new image component for the project. 2. Click Next on the New Image Component page. 3. Browse to the location of the images folder in the project:

<workspace>\HelloWorld\WebContent\images 4. Select all of the image files to be associated with the image policy. 5. Click Finish.



Page22 of 35

The new image policy will open with the policy editor, and you'll see several errors that say: "A value is required for 'Type'". We'll now configure the image policy and fix those errors. We'll also add the prefix /images/ to the asset value for each image.



Page23 of 35

1. Select the first asset, world-100.jpg, to configure its attributes. 2. Specify the following attributes on the right:

o Asset Value: /images/world-100.jpg (add prefix /images/)

o Asset Type: Device Specific Image o Device Name: Tablet

3. Repeat for world-20.gif with the following attributes:

o Asset Value: /images/world-20.gif

o Asset Type: Generic Image o Width Hint: 0



Page24 of 35

4. Repeat for world-20.jpg with the following attributes:

o Asset Value: /images/world-20.jpg


5. Repeat for world-20.png with the following attributes:

o Asset Value: /images/world-20.png


6. Repeat for world-40.jpg with the following attributes:

o Asset Value: /images/world-40.jpg

o Asset Type: Device Specific Image o Device Name: Smartphone

7. Save the changes to the image policy, hello.mimg. 8. Notice we have fixed all of the errors:



Page25 of 35

Now open the XDIME/JSP and add the snippet to any pane as follows

<pane name=”any_pane”>

<img serc=”/hello.mimg” alt=”hello”/>

</pane>

Save the project and Run on Server.

Test the image component

1. Right-click the HelloWorld project. 2. Select Run on Server. 3. Navigate to the portlet with the following user agent specified in FireFox:

o Description: Sanyo SCP-8100 o User Agent: Mozilla/4.0 (MobilePhone SCP-8100/US/1.0) NetFront/3.0 MMP/2.0



Page26 of 35

HelloWorld Portlet on Sanyo

4. Log off portal to end the previous session. 5. Navigate to the portlet with the following user agent specified in FireFox:

o Description: Smartphone o User Agent: Mozilla/2.0 (compatible; MSIE 3.02; Windows CE; Smartphone;)

HelloWorld Portlet on Smartphone

6. Log off portal to end the previous session. 7. Navigate to the portlet with the following user agent specified in FireFox:



Page27 of 35

o Description: Pocket PC o User Agent: Mozilla/2.0 (compatible; MSIE 3.02; Windows CE; PPC; 240x320)

HelloWorld Portlet on PDA

4.1.5 Using Spatial Iterator

A spatial iterator can be used to define both rows and columns in a single format. Format attributes can be used to specify the exact number of iterations or an upper limit, and also define the order of indexing the generated panes - rows or columns first. A single pane can be used to define a content that can be iterated programmatically with different set of data for rendering.



Page28 of 35

Spatial Iterator can be added to the Layout design as shown in the above screen. It is must to set the format attributes for the spatial Iterator. After adding the spatial Iterator, modify the XDIME/JSP accordingly so that the pane iteration is added. In general, following are the two different ways to add XDIME for the spatial Iteration of the panes of the layout Method 1: This uses the getPaneInstance – an mcs functional expression

Syntax: layout:getPaneInstance [pane_name_to_be_iterated, index]

<pane name="{layout:getPaneInstance('data', counter)}">

Data - <%= counter %>

</pane>

Method 2: <pane name=’<%=”data.” + counter %>’ >

Data - <%= counter %>

</pane>

In both ways the “data” pane (called as PaneStem) will be iterated using the JSP fragments with the specified number of Maximum count in the XDIME. ( Limit of the maximum rows or columns in the spatial Iterator format attributes is different from this limit, as the spatial Iterator format attributes one is to set the max number of possible panes the paneStem can iterate through)



Page29 of 35

4.1.6 Using Regions in Layouts

Each page is a template with some common content and a set of areas that can be occupied by variable content. The areas are known as regions. The content that occupies a region is known as a portlet. In MPA, a portal is a canvas with some specific attributes, and a region is a format that you define in a layout. The name provided to the region is associated with the XDIME markup with the name attribute of the region element.

In the above layout sample, there are two regions available for dynamically loading two different layouts.



Page30 of 35

XDIME/JSP for the above scenario can be logically represented as follows



Page31 of 35

4.1.7 Using CSS in JSP and Themes

1. Using separate JSP with style content as CSS. Following attached the project zip to demonstrate the same

In this case(1), a JSP with style definitions can be used to include in the XDIME and the class names can be mapped to the tags to style the Mobile portal rendering.

2. Using variant content within the themes, In this case, CSS classes and its definitions are placed within the theme files (variant content)

In case (2), below steps are followed

1. Create a theme file (*.mthm)



Page32 of 35

2. Add the necessary style in the form of CSS class definition, as shown in the testext.mthm - using MCS Source Editor.(Theme editor cannot be used in adding raw CSS content to the themes)

3. The class names used within the theme file (as added in step-2) can be used in the XDIME/JSP for styling.

Note:

- Once the variant content (as CSS) is included in the theme, themes files can be used only with the help of the MCS Source Editor. So it is recommended best practice to use combinations of all the above styling ideas to get a best output. (For use variant content to style default variant)

4.1.8 Differentiating Column Width & Pane Width In Layouts

COLUMN WIDTH - Width percentage the content has been allotted to occupy on the device's usable screen width

GRID/PANE WIDTH - Percentage of the width the to be occupied within the COLUMN WIDTH specified region.

Following describes the same with illustrations.

PANE WIDTH

GRID WIDTH

COLUMN WIDTH



Page33 of 35

HOW PANE WIDTH WORKS? (LAYOUT and OUTPUT)

Following illustrations clearly differentiates the width attributes of column and the pane.



Page34 of 35



Page35 of 35

5. REFERENCE

1. IBM Mobile Portal Accelerator Information center - http://publib.boulder.ibm.com/infocenter/mpadoc/v6r1m0/index.jsp

2. IBM Mobile Portal Accelerator Wiki - http://www-10.lotus.com/ldd/portalwiki.nsf/xpViewCategories.xsp?lookupName=IBM%20Mobile%20Portal%20Accelerator

3. Extending WebSphere Portal to a Mobile Audience - http://www.ibm.com/developerworks/websphere/library/techarticles/0411_burke/0411_burke.html

4. Developing a Mobile Portal Enabled XDIME Portlet - http://www.ibm.com/developerworks/websphere/library/techarticles/0412_balhoff/0412_balhoff.html

5. Using Components in XDIME Portlets - http://www.ibm.com/developerworks/websphere/library/techarticles/0505_dheap/0505_dheap.html

6. Develop Mobile Portlets with WebSphere Everyplace Mobile Portal - Part 1 & 2

Create an interactive XDIME portlet - http://www.ibm.com/developerworks/websphere/library/techarticles/0507_jadhav/0507_jadhav.html

Apply custom themes to mobile portlets - http://www.ibm.com/developerworks/websphere/library/techarticles/0509_jadhav/0509_jadhav.html

----------- End of Document ---------------

http://publib.boulder.ibm.com/infocenter/mpadoc/v6r1m0/index.jsp

http://www-10.lotus.com/ldd/portalwiki.nsf/xpViewCategories.xsp?lookupName=IBM%20Mobile%20Portal%20Accelerator



http://www.ibm.com/developerworks/websphere/library/techarticles/0411_burke/0411_burke.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0411_burke/0411_burke.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0412_balhoff/0412_balhoff.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0412_balhoff/0412_balhoff.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0505_dheap/0505_dheap.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0505_dheap/0505_dheap.html

http://www.ibm.com/developerworks/websphere/library/techarticles/0507_jadhav/0507_jadhav.html

Documents

Creating Layouts, Themes, Image components - IBM Layouts, Themes, Image components ... Mozilla Firefox browser with User ... In the design view of the theme editor, add a new Selector