68 Configuring Oracle WebCenter Sites: Mobility to Support Mobile Websites

Oracle WebCenter Sites: Mobility, also called Mobility, enables its users to create, preview, and deliver websites to a variety of mobile devices such as phones and tablets.

Implementing Mobility to support mobile-optimized websites requires configuring its framework. This chapter first presents the key concepts and outlines major features of the framework. Configuration procedures follow.

This chapter includes the following sections:

Section 68.1, "Prerequisites for Developers"
Section 68.2, "Key Mobility Concepts"
Section 68.3, "Prerequisites for Configuring Mobility Features"
Section 68.4, "Configuring Mobility Features"
Section 68.5, "Device Detection"

68.1 Prerequisites for Developers

Configuring the Mobility framework requires you to have experience with core WebCenter Sites features, including site plans and templates. Also required is an understanding of mobile devices and their user agents.

68.2 Key Mobility Concepts

WebCenter Sites uses a built-in device detection mechanism to identify the device that requests website content. Once the device is identified, WebCenter Sites finds the appropriate site plan (site navigation) and invokes the correct template to render the website.

The mechanics of this device detection process involve new features, such as device repository, device groups and suffixes, device assets, template variants, and site plans (which have been extended to support mobile websites). This section describes the concepts behind the new features. Later sections provide procedures for configuring the features to support mobile websites.

Once the features are configured, it is possible in the Contributor interface to create, preview, and deliver mobile sites, such as the site shown in Figure 68-1. In this figure, the Home page of the avisports sample site is displayed in the context of three devices (multi-device preview).

Figure 68-1 Preview of Avisports Site Home Page in the Context of Multiple Devices in the Contributor Interface

Description of "Figure 68-1 Preview of Avisports Site Home Page in the Context of Multiple Devices in the Contributor Interface"

This section contains the following topics:

Section 68.2.1, "Device Repository"
Section 68.2.2, "Device Groups and Suffixes"
Section 68.2.3, "Device Assets"
Section 68.2.4, "Site Plans"
Section 68.2.5, "Mobile Templates"

68.2.1 Device Repository

The device repository is a file that WebCenter Sites uses to detect mobile devices. The device repository contains the properties of devices and uniquely identifies each device based on its user agent. Device detection is accomplished by WebCenter Sites matching the user agent of the device to the user agent that is specified in the device repository.

Note:

A user agent is a software agent that acts on behalf of users. The format of a user-agent string is a list of product tokens (keywords) with optional comments. Most browsers specify the following format:

Mozilla[version] (system and browser information]) [ platform] ([platform details]) [extensions]

For example:

Mozilla/so(iPad;u;CPUOS 3.2.1 like Mac OSx;en-us)ppleWebkit/531.21.10(KHTML,like Gecko) Mobile/7B405

The two types of device repositories are:

devices.xml: This is the default repository included with WebCenter Sites. This repository is updated at the time of a product release and includes only popular devices. You can add more data to this repository as and when required.
WURFL: This is a third-party device information database from ScientiaMobile. WURFL is much more comprehensive than devices.xml, and it is updated regularly by ScientiaMobile. We recommend using WURFL to ensure you have the latest devices. A licensed copy can be obtained from ScientiaMobile. It is not included with WebCenter Sites.

For procedures on using the desired device repository, see Section 68.4.2, "Step 2: Setting Up the Device Repository."

68.2.2 Device Groups and Suffixes

Device Groups enable features-based grouping of devices. A device group is an asset that defines a collection of devices with common characteristics, for which a common website can be delivered. For instance, all Touch phones could belong in one group, whereas NonTouch (QWERTY) phones could be in a separate group, as illustrated in Figure 68-2.

Figure 68-2 Device Type-Based Grouping

Description of "Figure 68-2 Device Type-Based Grouping"

One website can be delivered to all the Touch devices. Another website can be delivered to all the NonTouch (QWERTY) devices. Therefore, two sets of templates must be coded: one set for the group of Touch devices, and another set for the group of NonTouch devices.

This is where we introduce the concept of suffixes. Suffixes are used to associate templates to the correct device groups. The association is made when the template and device group have the same suffix, such as _Touch (or _NonTouch). For example, if the base template HomeLayout is used to render the desktop website, you would create template variants, that is, templates named HomeLayout_suffix. In this example, you would create the HomeLayout_Touch template to render content on devices in the Touch device group; you would also create the HomeLayout_NonTouch template to render content on devices in the NonTouch device group.

At runtime, WebCenter Sites will match the suffixes of the device groups to the names of the template variants so that if HomeLayout is requested from a Touch device, WebCenter Sites will use the HomeLayout_Touch template to render the website. This is part of device detection.

Note:

A template without a suffix is called the base template. Templates with suffixes are called variants of the base template. The base template must exist before its variants can be created.

Suffixes are also used to associate device groups to site plans, which enables you to implement different website navigation for devices in different device groups. Templates are coded with the device:siteplan tag to specify website navigation on the delivery system.

To create a device group, you will create an asset of type DeviceGroup. In the process, you will specify:

A suffix.
Either the registered device name(s), or criteria that WebCenter Sites will use to associate devices to the group you are creating.

Note:

If you create multiple device groups, you will have to prioritize them for proper matching of devices to device groups during device detection.

For procedures on configuring device groups, see Section 68.4.3, "Step 3: Configuring Device Groups." For procedures on prioritizing device groups, see Section 68.4.4, "Step 4: Prioritizing Device Groups."

68.2.3 Device Assets

Any mobile device can be represented by a device asset, which enables previewing of mobile website content in the context of the mobile device, in the Contributor interface. Device assets are used strictly to support preview. Even when devices are similar enough to be gathered in the same device group, they display variations (for example, screen size). Previewing in the context of a device asset enables content contributors to ensure that content will be rendered properly on the corresponding real device.

A device asset consists of an image and a user agent. The user agent is used to associate the device asset to (1) a real device in the device repository and (2) to a device group with matching criteria. For an example of associations illustrating the relationship between device groups and device assets, see Figure 68-3.

Figure 68-3 Devices Associated with Device Groups

Description of "Figure 68-3 Devices Associated with Device Groups"

Device assets are associated to device groups by device detection. If a device asset matches the criteria specified in two or more device groups, the device asset is automatically associated to your preferred (highest-priority) device group. If a device fails to match criteria in all device groups, it is automatically assigned to the Default device group (used for serving websites to desktop browsers). Once a device is associated to a device group, templates associated with that device group can render website content in preview mode. The content is superimposed on the device image.

Note:

Ensure that content contributors are aware of the following preview behavior:

While preview of web pages in mobile devices works in all browsers, some features will not be displayed correctly if there is a mismatch between the browser and the user agent. For example, if the Contributor interface is opened in Internet Explorer, whereas the user agent is for FireFox on Android, the browser will use the Internet Explorer engine to render HTML. Therefore, previews in the Contributor interface are likely to differ from the look of the real pages on the real mobile device.
Preview renders pages as they would be displayed in full-screen mode on real devices.

For procedures about creating devices, see Section 68.4.5, "Step 5: Creating Device Assets."

68.2.4 Site Plans

A site plan defines the navigational hierarchy of a website. For example, Figure 68-4 shows the following site plans for the avisports sample site in the Contributor interface: Default, Touch, and NonTouch.

Figure 68-4 Site Plans in the Contributor Interface

Description of "Figure 68-4 Site Plans in the Contributor Interface"

When creating a site plan, you will associate device groups to that site plan by selecting a shared suffix. Site navigation defined by that site plan can then be served to devices in those device groups. (Once selected, the suffix is no longer available for other site plans.)

You have two basic approaches to creating site plans:

Create a single site plan for all devices across all device groups.
Create multiple site plans. Different site plans for different device groups allows for different navigation. The content can be re-used across site plans, or it can be different across site plans.

For procedure on configuring site plans, see Section 68.4.6, "Step 6: Creating Site Plans."

68.2.5 Mobile Templates

You have two basic approaches for creating templates that render mobile websites:

Create a single set of templates that adapt to all mobile devices (and therefore all device groups). Adaptive templates adapt to the screen resolution of a device and render content suitably. In this scenario, there is no need for creating templates with suffixes.
Create different templates for different device groups. (An example was described in Section 68.2.2, "Device Groups and Suffixes.")

This scenario requires you to create two sets of templates: One set contains the base templates (without any suffixes). The other set contains the template variants (templates with suffixes). To create a template variant, you will append _suffix to the name of the base template.

For example, if you create a device group called iPhones with suffix Touch, then your template name will be BaseTemplateName_Touch. This naming convention and the matching of suffixes for device groups and templates ensures that WebCenter Sites routes requests from mobile devices to the correct template variants. If a mobile template variant does not exist for a specific device group, the base template is used instead.

Note:

WebCenter Sites does not recognize templates with two suffixes (such as _Touch_NonTouch), and therefore, such templates are not available through the Choose Page Layout option on the asset toolbar in the Contributor interface. If you do create a template with two suffixes, this template will not be considered a variant of an existing template, and so, it will not be used for rendering assets. The base template will be used instead.

You can create template variants at any time after you have created the device groups and therefore, specified the suffixes. For more information about creating templates, see Section 68.4.8, "Step 8: Creating Templates."

68.3 Prerequisites for Configuring Mobility Features

Before you start configuring Mobility features, ensure you have the following credentials and information:

You have either the SiteAdmin or GeneralAdmin role. In this chapter, we assume you have the GeneralAdmin role.
An understanding of which device repository you will be using. For more information about your options and procedures, see Section 68.4.2, "Step 2: Setting Up the Device Repository."
The names of device groups in which to organize different devices.
Which capabilities (such as user agent, touch, tablet, and screen resolution) you will use to identify and group devices. For more information as to which data you will provide, see Section 68.4.3, "Step 3: Configuring Device Groups."
Which suffix you will use for each device group. A suffix is required for each device group. (You will append the same suffix to the names of the template variants for these device groups. You will also select the same suffix for the site plan.)
The list of devices your contributors will be using to preview the mobile website. WebCenter Sites comes with a number of device assets that represent many commonly used devices.

If you need to create your own device assets, first create your own images of the real devices, and look up the user agents of the real devices. You will use these images and user-agent information to create device assets. Also create their thumbnail images for use in the device selector panel in the Contributor interface.
Effective site plans for the mobile versions of your website.

68.4 Configuring Mobility Features

This section contains the following topics:

Section 68.4.1, "Step 1: Enabling the Mobility Tab"
Section 68.4.2, "Step 2: Setting Up the Device Repository"
Section 68.4.3, "Step 3: Configuring Device Groups"
Section 68.4.4, "Step 4: Prioritizing Device Groups"
Section 68.4.5, "Step 5: Creating Device Assets"
Section 68.4.6, "Step 6: Creating Site Plans"
Section 68.4.7, "Step 7: Organizing Site Plans"
Section 68.4.8, "Step 8: Creating Templates"

68.4.1 Step 1: Enabling the Mobility Tab

The only user who is automatically granted access to the Mobility tab in the Admin interface is the user whose credentials were used during the WebCenter Sites installation process. This user was automatically assigned the MobileSitesDeveloper role. Other users must be explicitly assigned the MobileSitesDeveloper role so they can use this tab.

68.4.2 Step 2: Setting Up the Device Repository

In this step, you have the option to use one of the following device repositories:

devices.xml

If you want to use this file, ensure that it is active. For instructions, see Section 68.4.2.1, "Determining Which Device Repository is Active."

If you need to make changes to this file, you will have to modify the file and re-upload it to WebCenter Sites. For instructions on setting up devices.xml, see Section 68.4.2.2, "Modifying the Default Device Repository."
WURFL

You will need to obtain a licensed version of this repository from ScientiaMobile. It is not included with WebCenter Sites.

The WURFL repository can be uploaded in one of two formats:
- WURFl.zip
- WURFL.xml with a WURFL patch file. The patch file is used to override the content of WURFL.xml. For more information about patch files, see http://wurfl.sourceforge.net/. For instructions on setting up WURFL, see Section 68.4.2.3, "Uploading the Third-Party Device Repository."

68.4.2.1 Determining Which Device Repository is Active

On the Mobility tab, double-click the Device Repository node.
In the Device Repository Uploader form, note which repository is selected: Default Repository (which means devices.xml is active) or one of the WURFL files.

Figure 68-5 Device Repository Uploader

Description of "Figure 68-5 Device Repository Uploader"
Continue with one of the following steps:
- If you need to change the device repository, complete one of the following sections:
  - Section 68.4.2.2, "Modifying the Default Device Repository"
  - Section 68.4.2.3, "Uploading the Third-Party Device Repository"
- If you are satisfied with the current active repository, continue to Section 68.4.3, "Step 3: Configuring Device Groups."

68.4.2.2 Modifying the Default Device Repository

In this step, you will ensure the following:

The devices.xml file contains the device names and user agents you require.
The devices.xml file is active.

To set up the devices.xml file:

Locate devices.xml in the following directory: <WebCenterSites>\11gR1\Sites\11.1.1.8.0\Shared\Storage\DeviceRepository\902\235\devices.xml, make the necessary changes, and continue with this procedure.
Upload devices.xml to WebCenter Sites:
1. In the Admin interface, navigate to the Mobility tab.
2. Double-click Device Repository.
3. In the Device Repository Uploader form, select the Default Repository option, if not selected by default.
4. In the Upload Default Repository section, click Browse and select the path to devices.xml.
  
  Note:
  
  If you changed device names in devices.xml, you are reminded to update the corresponding device names in all the device groups you might have already been created.
5. Click the Save icon.
Continue to Section 68.4.3, "Step 3: Configuring Device Groups."

68.4.2.3 Uploading the Third-Party Device Repository

If you need to support more capabilities and devices than already registered in the devices.xml file, you can use WURFL as the device repository. WURFL can be uploaded as WURFL.zip or wurfl.xml and its patch file.

Note:

WURFL is a third-party device repository. You must purchase a license in order to use this repository.

If you plan to use the wurfl.xml file and patch, ensure the patch file is configured before you start this procedure.

To upload WURFL:

In the Admin interface, navigate to the Mobility tab.
Double-click Device Repository.
In the Device Repository Uploader form, go to the WURFL section, and upload either the complete WURFL zip file, or the main wurfl.xml file and a patch file.

Note:

After the WURFL.patch file is uploaded, it is used with the WURFL.xml file, regardless of the fact that the record for WURFL.patch in the device repository table is still set to Active=F (false).
Continue to Section 68.4.3, "Step 3: Configuring Device Groups."

68.4.3 Step 3: Configuring Device Groups

To configure a device group:

On the Mobility tab, expand the Device Groups node.
Click Add Device Group, as shown in Figure 68-6.

Figure 68-6 Add Device Group

Description of "Figure 68-6 Add Device Group"

The Device Group form is displayed, as shown in Figure 68-7.

Figure 68-7 Device Group Form

Description of "Figure 68-7 Device Group Form"
In the Device Group form, select the Content tab and do the following:
1. In the Name field, enter a meaningful name for the device group you are creating.
2. In the Suffix section, enter the suffix you plan to use for the templates you will create for this device group (Figure 68-7). You can choose an existing suffix if there is any.
  
  Note:
  
  This suffix is not editable. If you want to change it later, you will have to recreate this device group and change this suffix.
3. In the Active field, enable this device group for device detection by selecting Yes.
  
  Note:
  
  Device groups are global. Once enabled, they become available for all sites. Similarly once disabled, they are disabled for all sites and will no longer be used in device detection.
Select the Criteria tab (Figure 68-8) to create a set of rules for matching real devices so they can be associated with their correct template variants.

You can either provide one or more device names (the rest of the form will be disabled (see Figure 68-8), or you can omit the device name(s) and fill in the rest of the form.

Figure 68-8 Add Device Names

Description of "Figure 68-8 Add Device Names"
1. If you choose to enter device name(s), enter the same name(s) that are registered in the device repository you chose to use in Section 68.4.2, "Step 2: Setting Up the Device Repository." If you uploaded devices.xml, enter the device entry name. If you uploaded WURFL, enter the model_name of the device.
  
  Note:
  
  A device can belong to only one device group at a given time.
  
  Continue to Section 68.4.4, "Step 4: Prioritizing Device Groups."
2. If you choose to omit device names, fill in the rest of the form, as follows:
  1. User-Agent Section. (This section is disabled if you specify the device names.)
    
    In this field, you can enter just a list of device names, or a combination of user agent, screen dimensions, capabilities, and custom filters. A combination of user-agent regex, capabilities, screen dimensions, and custom filter requires a device to meet all the rules to match with the device group.
    
    Enter the exact user agent of the browser from which the incoming request will be sent. Or, you can enter a regular expression or a substring to match the set of the user agents. For example, to match all iPhone user agents, specify the user-agent reg exp as (m|M)ozilla/5.0(| )\(i(p|P)(hone|od|rod).* This expression will match any user-agent string which contains the iPhone Java regex. Or, you can use the substring iPhone; which matches all iPhones.
  2. Capabilities Section. (This section is disabled if you specify the device names.)
    
    The capabilities are Touch Screen, JavaScript, Dual Orientation, and Is Tablet. Each capability gives you the following options: Yes, No, Don't evaluate.
    
    For example, if you want this device group to match only Tablet devices that do not support JavaScript, then for the IsTablet capability, select Yes; for the JavaScript capability, select No; and for the rest of the capabilities, select Don't evaluate.
  3. Screen Resolution Section. (This section is disabled if you specify the device names.)
    
    Enter the minimum and maximum width and height for the display area (units are in pixels).For example, if you specify a maximum width of 640, then all devices whose screen resolution width is 640 or less will match this device group.
  4. In the Custom Device Filters section, click Browse to choose a custom filter that you might have created to apply conditions on capabilities that are not listed on the Device Group Criteria tab. For information about creating custom filters to set device criteria, see Section 68.4.3.1, "Creating Custom Filters for Device Group Criteria."
Click the Save icon to save your device group.

Your new device group is listed on the Mobility tab, at the bottom of the Device Groups node (Figure 68-9).

Figure 68-9 New Device Group

Description of "Figure 68-9 New Device Group"

Note:

Once you prioritize your device groups and create the device assets, you can verify that they are correctly associated by device detection. To do so, open the device group and select the Devices tab to view the list of device assets associated with the device group.

For procedures on prioritizing device groups, see Section 68.4.4, "Step 4: Prioritizing Device Groups."

For procedures on creating device assets see Section 68.4.5, "Step 5: Creating Device Assets."
Continue to Section 68.4.4, "Step 4: Prioritizing Device Groups."

68.4.3.1 Creating Custom Filters for Device Group Criteria

WebCenter provides a default custom filter implementation (DefaultCustomFilter.java), which takes an XML file as input. To create a custom filter of your own, you can write an implementation of the CustomDeviceFilter.java interface. The XML file for a custom filter is uploaded from the Device Group configuration screen, as described in Section 68.4.3, "Step 3: Configuring Device Groups."

This section includes the following:

Using the Default DefaultCustomFIlter.java Custom Filter Provided with WebCenter Sites
Creating Your Own DeviceGroupFilter Implementation

Using the Default DefaultCustomFIlter.java Custom Filter Provided with WebCenter Sites

The default implementation class of a custom filter is called COM.FutureTense.Mobility.Filter.DefaultCustomFilter. It takes input in XML format. In the default custom filter implementation provided with WebCenter Sites, a filter is passed only if all its arguments are passed. Similarly, an entire custom filter is passed when all its filters are passed. So, in any scenario, all arguments must be passed for the filter criteria to work.

Example 68-1 shows a sample filter XML in which device property names are taken from the WURFL repository.

Example 68-1 Sample Filter Based on DefaultCustomFIlter.java and WURFL Repository

<?xml version="1.0" encoding="UTF-8"?>
<devicefilters>
       <filter name="tabletFilter" classname="COM.FutureTense.Mobility.Filter.DefaultCustomFilter"> //Filter 1
             <argument name="is_tablet" value="true" datatype="boolean"/> //argument 1 of filter 1
             <argument name="pointing_method" value="touchscreen" datatype="string" operator="equals"/> //argument 2 of filter 1
       </filter>
             <filter name="flashFilter" classname="COM.FutureTense.Mobility.Filter.DefaultCustomFilter"> //Filter 2
             <argument name=" full_flash_support" value="false" datatype="boolean"/> //argument 1 of filter 1
       </filter>
</devicefilters>

In the above sample, tabletFilter has two arguments. argument 1 requires that the value of the is_tablet property should be true. argument 2 requires that the value of the pointing_method property should be touchscreen. flashFilter has only one argument which is, the value of the full_flash_support property should be false. Each argument is a rule and a complete filter. Only when every argument is met, a device can match to the device group containing the above custom filter.

This sample XML uses device property names from the WURFL repository. If the default device repository (devices.xml) is used, then this XML looks something like Example 68-2 (notice that the property names have changed). In this filter XML, there are two filters: tabletFilter and flashFilter.

Example 68-2 Sample Filter Based on DefaultCustomFIlter.java and Devices.xml Repository

<?xml version="1.0" encoding="UTF-8"?>
<devicefilters>
       <filter name="tabletFilter" classname="COM.FutureTense.Mobility.Filter.DefaultCustomFilter"> //Filter 1
           <argument name="tablet" value="true" datatype="boolean"/> //argument 1 of filter 1
           <argument name="touch" value="true" datatype="string" operator="equals"/> //argument 2 of filter 1
       </filter>
       <filter name="flashFilter" classname="COM.FutureTense.Mobility.Filter.DefaultCustomFilter"> //Filter 2
           <argument name="flash" value="false" datatype="boolean" /> //argument 1 of filter 1
       </filter></devicefilters>

While creating a custom filter based on DefaultCustomFIlter.java, consider the following:

In a custom filter, possible values of the datatype argument attribute are string, number, boolean. Default value is string.
- When datatype = number, the possible values of the operator attribute are: <>, notequals, <, lt, >, gt, =, equals. Default value is equals.
- When datatype = boolean, the possible values of the operator attribute are: =, equals. Any other value is treated as the reverse of equals. Default value is equals.
- When datatype = string, the possible values of the operator attribute are =, equals, %, like, !=, notequals, !%, notlike. Default value is equals. The following snippet shows the use of the like or % value for the operator attribute:
```
<argument name="pointing_method" value="touch" datatype="string" operator="like"/>
```
  Here, the value of the pointing_method property must contain the word touch either as a substring or an entire word.
The value of the property attributes must be as per the property names in the current device repository (either devices.xml or WURFL.xml).

Creating Your Own DeviceGroupFilter Implementation

You can create a Java class that implements the DeviceGroupFilter interface (Example 68-3) and uses the matches method. Your custom filter can consist of one or more filters. Each filter can contain zero or more arguments. The custom filter implementations can use the OR rule, or any custom logic.

Example 68-3 A Java Class That Implements the DeviceGroupFilter Interface and the matches Method

public class UserDefinedCustomFilter implements DeviceGroupFilter
{
public boolean matches(DeviceContext context)
    {
       // Logic that returns true/false depending on whether criteria matched or not.
    }
}

68.4.4 Step 4: Prioritizing Device Groups

Multiple device groups must be prioritized to enable device detection to automatically associate a real device to the highest-priority device group at runtime.

To prioritize device groups:

On the Mobility tab, expand the Device Groups node.
Double-click Reorder Device Groups (Figure 68-10).

Figure 68-10 Reorder Device Groups

Description of "Figure 68-10 Reorder Device Groups"
In the Reorder Device Groups screen, drag and drop the device groups in the order of your preferred priority (Figure 68-11).

Figure 68-11 Drag and Drop Device Groups

Description of "Figure 68-11 Drag and Drop Device Groups"

When you have reordered the device groups, the Reorder Device Groups screen displays them in the new sequence (such as the one in Figure 68-12).

Figure 68-12 Device Groups Reordered

Description of "Figure 68-12 Device Groups Reordered"
Click Save Priority.

The Device Groups have been re-prioritized successfully message is displayed.
Continue to Section 68.4.5, "Step 5: Creating Device Assets."

68.4.5 Step 5: Creating Device Assets

To create a device asset:

On the Mobility tab, expand the Devices node.
Click Add Device (Figure 68-13).

Figure 68-13 Add Device

Description of "Figure 68-13 Add Device"

The Device form is displayed, as shown in Figure 68-14.

Figure 68-14 Device Form - Content Tab

Description of "Figure 68-14 Device Form - Content Tab"
On the Content tab (Figure 68-14):
1. In the Name field, enter a name for this device asset.
  
  The name that you enter will be displayed in the Contributor interface. It does not have to match the name in the device repository.
2. (Optional). In the Manufacturer field, enter the name of the device maker company.
3. In the User Agent field, specify the registered user agent for the device whose image you are adding. You can copy the user agent from the device repository.
  
  Note:
  
  The user-agent field identifies which real device this device asset represents. This field is used in device detection logic to associate this device with the matching device group of highest priority.
4. Click Test User Agent to run device detection and confirm that this device matches a particular device group.
5. Select the Enable checkbox to make this device asset available for association to device groups by device detection.
6. Next to the Device image field, click Browse to select the device image from the directory in which the image is stored.
7. (Optional). Next to the Thumbnail image field, upload a thumbnail image. This thumbnail image will be displayed in the device selector panel that is associated with the preview feature in the Contributor interface. Selecting the thumbnail displays a page preview in the device image.
On the Screen Dimensions tab, enter the required pixels in the Height, Width, Top, and Left fields and pixel ratio in the Pixel Ratio field to determine an appropriate dimension of the screen area.

As you enter the pixels in each field, the screen area of the device image begins to reset accordingly. This feature lets you determine the exact dimension of the device display area on the spot.

Figure 68-15 Screen Dimensions Tab

Description of "Figure 68-15 Screen Dimensions Tab"
Click the Save icon on the form to create the new device.

The success message is displayed.
Continue to Section 68.4.6, "Step 6: Creating Site Plans."

68.4.6 Step 6: Creating Site Plans

Whether you need multiple site plans or a single site plan depends on your design approach.

When creating a site plan, you will associate device groups to that site plan by selecting a common suffix. Once selected, that suffix is no longer available for other site plans.

To create a site plan:

In the Admin interface, open the Admin tab, and expand the Sites node and the site for which you are creating the site plan.

Note:

(If you are assigned the SiteAdmin role, use the Site Admin tab instead.
Expand the Site Plans node.
Double-click Add New (Figure 68-16).

Figure 68-16 Site Plans Node in the Admin Tab

Description of "Figure 68-16 Site Plans Node in the Admin Tab"

The Add Site Plan page is displayed (Figure 68-17).

Figure 68-17 Add Site Plan

Description of "Figure 68-17 Add Site Plan"
In the Name field, enter a meaningful name for your site plan.
(Optional) In the Description field, enter a description for your site plan.
To associate device groups with this site plan, go to the Suffix section, and select a suffix used by those device groups.

Note:

The Suffix section lists only suffixes that are not assigned to any site plans.

The Associated Device Groups panel (Figure 68-18) lists the device groups that are associated with your selected suffix.

Figure 68-18 Associated Device Group Panel

Description of "Figure 68-18 Associated Device Group Panel"
Click Add to complete the site plan.

A screen similar to Figure 68-19 is displayed.

Figure 68-19 New Site Plan Created

Description of "Figure 68-19 New Site Plan Created"
Click the Site Plan tab to see the newly created site plan.

To modify the site plan, double-click it under your site's node on the Admin tab. On the Modify Site Plan page, make the desired changes and then click Modify. Continue to Section 68.4.7, "Step 7: Organizing Site Plans."

68.4.7 Step 7: Organizing Site Plans

You can reorder site plans if they should be displayed in a specific order in the Admin and Contributor interfaces.

To organize site plans:

In the Admin interface, open the Admin tab, and expand the Sites node and the site for which you are prioritizing the site plans.

Note:

(If you are assigned the SiteAdmin role, use the Site Admin tab instead.
Double-click Reorder Site Plans.

Figure 68-20 Reorder Site Plans

Description of "Figure 68-20 Reorder Site Plans"
In the Reorder Site Plans screen (Figure 68-21), drag and drop site plans to order them in the preferred sequence.

Figure 68-21 Drag and Drag Site Plans

Description of "Figure 68-21 Drag and Drag Site Plans"

When you have reordered the site plans, the Reorder Site Plans screen looks something like Figure 68-22.

Figure 68-22 Site Plan Reordered

Description of "Figure 68-22 Site Plan Reordered"
Click Save.

The Modification was successful message is displayed.
Continue to Section 68.4.8, "Step 8: Creating Templates."

68.4.8 Step 8: Creating Templates

You have two basic approaches for creating templates that render mobile websites:

Create a single set of templates that adapt to all mobile devices (and therefore all device groups).
Create different templates for different device groups. This scenario requires the use of suffixes.

This section discusses the second approach. This section contains the following topics:

Section 68.4.8.1, "Basic Guidelines for Creating Template Variants"
Section 68.4.8.2, "Mobility Tags"
Section 68.4.8.3, "Tags Modified to Support Device Detection and Page Rendering"

68.4.8.1 Basic Guidelines for Creating Template Variants

When creating different templates for different device groups, note the following requirements:

Create the base template (the template that renders the desktop website).
Create the template variant by using the name of the base template and appending _suffix.
If you intend to cache pages based on your templates, you must use the suffix (the d parameter) as one of the cache criteria.

68.4.8.2 Mobility Tags

Table 68-1 describes the Mobility tags you will use when creating templates. For detailed information about the tags, see the Oracle Fusion Middleware WebCenter Sites Tag Reference.

Table 68-1 Tags for Mobility

Tag	Description
`<device:load name="<Name of Current Device>" />`	Detects the current device and loads the device information. Similar to `asset:load`.
`<device:get name="<Name of Current Device>" property="useragent\|devicegroup\|suffix" [output="propName"] />`	For a loaded device, this tag returns the value of one of the following properties: `useragent`, `devicegroup`, or `suffix`. If the optional attribute `output` is provided, this tag sets the value of the property in the `output` variable. If the `output` attribute is absent, this tag sets the value of the property to a variable with the name of that property.
`<device:if name="<Name of Current Device>" property="touch" value="true" [datatype="boolean"] [operator="equals"] > ... conditional code for touch devices only ... </device:if>`	For the currently loaded device, this tag allows you to specify a condition and code that will be executed when the condition is met. The default value for the optional attribute `datatype` is `String,` and the default value for the optional attribute `operator` is `"="`.
`<device:hascapability name="<Name of the Device Loaded Earlier>" capability="<WURFL_CAPABILITY_NAME>" > conditional code </device:hascapabiilty>`	For the currently loaded device, this tag checks if this device supports the capability specified in this tag. If the device supports this capability, the code in the tag is executed.
`<device:capability name="<Name of the Device Loaded Earlier>" capability="<WURFL_CAPABILITY_NAME>" output="capabilityValue" />`	For the currently loaded device, this tag sets the value of the specified capability in the `ics` scope.
`<device:siteplan output=<NAME_OF_VARIABLE_HOLDING_RESULTING_SITEPLAN_ID> [pubid = <%=ics.GetVar("pubid")%>] [site=<%=ics.GetVar("site")%>] [d= <%=ics.GetVar("d")%>] />`	You can use the `device:siteplan` tag to look up the site plan for any device. The tag takes the `d` parameter, which is a device group suffix. At runtime, WebCenter Sites computes the value of the `d` parameter by using device detection. The tag then uses the value of the `d` parameter (that is, the suffix) to find the site plan with the same suffix and to return the ID of that site plan. The site plan ID is used by other tags to construct website navigation.

68.4.8.3 Tags Modified to Support Device Detection and Page Rendering

The following tags include Mobility-specific attributes:

render:getpageurl
render:calltemplate
render:gettemplateurl
render:gettemplateurlparameters
insite:calltemplate
satellite:page
satellite:link

The attributes are:

d, the suffix of a device group.
resolvetemplatefordevice, which appends the device group suffix to the template name. The default value is true. If the value is set to false, the suffix is not appended to the template name and the base template is loaded.

The d parameter is automatically passed down the chain in each of the tags above. The tags call the correct template variant by basing their call on the passed d attribute.

In the following example for the avisports sample site, c=Page and TestSite is the current site.

<render:calltemplate tname='Detail' args="c,cid,p,d,locale,form-to-render" />
(i) for d=Desktop (default) or blank, the following template is called:
         TestSite/Page/Detail
(ii) for d=Touch, the following template is called: 
         TestSite/Page/Detail_Touch

For information about how the d attribute is used, see Section 68.5, "Device Detection."

68.5 Device Detection

WebCenter Sites uses a built-in device detection mechanism to identify the device that requests website content. Once the device is identified, WebCenter Sites looks for the matching device group and reads its suffix. Using the suffix, WebCenter Sites finds the site plan and invokes the template variant to render the content.

The detailed steps are as follows:

A page request from a real device is received by Remote Satellite Server. The header for this request includes the user agent of the device.
Remote Satellite Server looks for the page in its own cache. If it fails to find the page, Remote Satellite Server sends the page request to WebCenter Sites.
WebCenter Sites responds as follows:
1. Identifies the device by its user agent in the request header.
2. Looks for the user agent in the device repository.
3. If it finds a matching device in the device repository, WebCenter Sites also finds the capabilities of that device.
4. WebCenter Sites then uses the user agent and device capabilities to find device groups with matching criteria.
5. Associates the device to the highest-priority device group.
6. Reads the suffix for this device group.
7. Assigns the suffix to the d parameter in the ics scope.
8. Appends _suffix to the requested template name in the URL.
9. Appends d=suffix to the URL of the requested page.
  
  For example:
  
  If the suffix is Touch, WebCenter Sites converts the original URL pagename=avisports/HomeLayout1&c=Page&cid=1482760932
  
  to the following URL:
  
  pagename=avisports/HomeLayout1_Touch&c=Page&cid=1482760932&d=Touch
10. If the template variant exists, WebCenter Sites executes the new URL, caches the page, and sends it to Remote Satellite Server.
  
  If the template variant does not exist, WebCenter Sites executes the original URL, caches that page, and sends it to Remote Satellite Server.
Remote Satellite Server caches the page and sends the response back to the device.
Remote Satellite Server also caches device detection information and uses it to process subsequent requests from the same device. This prevents WebCenter Sites from re-running device detection.