26 Configuring WebCenter Sites to Support Mobile Websites

Mobility enables its users to create, preview, and deliver websites to a variety of mobile devices such as phones and tablets. You need to configure the Mobility framework to enable WebCenter Sites to support mobile-optimized websites.

Topics:

26.1 Prerequisites for Mobility Developers

You should have an experience with core WebCenter Sites features including site navigations and templates to be able to configure the Mobility framework.

You should also have an understanding of mobile devices and their user agents.

26.2 Understanding 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 navigation (called site navigation in the previous release) 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 navigations (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 Oracle WebCenter Sites: Contributor interface to create, preview, and deliver mobile sites, such as the site shown in the figure below. In this figure, the Home page of the avisports sample site is displayed in the context of three devices (multi-device preview).

Figure 26-1 Preview of avisports Site Home Page in the Context of Multiple Devices in the Contributor Interface

Description of Figure 26-1 follows
Description of "Figure 26-1 Preview of avisports Site Home Page in the Context of Multiple Devices in the Contributor Interface"

Topics:

26.2.1 About 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. WebCenter Sites detects devices by 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 about using the device repository, see How to Configure the Device Repository.

26.2.2 About 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 the next figure. So, one website is delivered to all the Touch devices. Another website is 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.

Figure 26-2 Device Type-Based Grouping

Description of Figure 26-2 follows
Description of "Figure 26-2 Device Type-Based Grouping"

To support template variants, the concept of suffixes has been introduced. 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. When 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 navigations, 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:

    Multiple device groups should be prioritized for proper matching of devices to device groups during device detection.

See How to Configure Device GroupsandHow to Prioritize Device Groups

26.2.3 About 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 this figure:

Figure 26-3 Devices Associated with Device Groups

Description of Figure 26-3 follows
Description of "Figure 26-3 Devices Associated with Device Groups"

Device assets are associated to device groups by device detection. A device asset that matches the criteria specified in two or more device groups is automatically associated to your preferred (highest-priority) device group. A device that fails to match criteria in all device groups 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 are not 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.

See How to Create Device Assets.

26.2.4 About Site Navigations

A site navigation defines the navigational hierarchy of a website. For example, the next figure shows Default, Touch, and NonTouch site navigations for the avisports sample site in the Contributor interface.

Figure 26-4 Site Navigations in the Contributor Interface

Description of Figure 26-4 follows
Description of "Figure 26-4 Site Navigations in the Contributor Interface"

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

You have two basic approaches to creating site navigations:

  • Create a single site navigation for all devices across all device groups.

  • Create different site navigations for different device groups. The content can be reused across site navigations, or it can be different.

See How to Create Site Navigations.

26.2.5 About 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 About 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 append _suffix to the name of the base template.

    For example, the template name for a device group called iPhones, whose suffix is Touch, 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. The base template is used whenever a mobile template variant does not exist for a specific device group.

    Note:

    WebCenter Sites does not recognize templates with two suffixes (such as _Touch_NonTouch). They are not considered variants of existing templates. Such templates are not available through the Choose Page Layout option on the asset toolbar in the Contributor interface, and therefore, they are not used for rendering assets. The base template is used in place of a template that has two suffixes.

You can create templates at any time once you have created the device groups and you know the suffixes. See Creating Templates.

26.3 Prerequisites for Configuring Mobility Features

To be able to configure Mobility features, you should have the necessary credentials and information. For example, the GeneralAdmin role, device repository, and so on.

  • The only user who is automatically granted access to the Mobility tab in the Admin interface is the user with the GeneralAdmin role.

    Note:

    The MobileSitesDeveloper role is no longer available. If you have upgraded from 11.1.1.8.0 release, be aware that MobileSitesDeveloper role acts as a user-defined role and has no particular significance. Therefore, you must grant access to the Mobility tab to the GeneralAdmin role.

  • An understanding of which device repository you will be using. See How to Configure the Device Repository.

  • Information about the device groups you will be configuring.

    • 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 How to Configure 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 navigation.)

    • Whether you will use custom filters to apply conditions on capabilities that are not listed by default. See How to Create Custom Filters for Device Group Criteria.

  • The list of devices your contributors will be using to preview the mobile website. WebCenter Sites comes with several device assets that represent many commonly used devices.

    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 navigations for the mobile versions of your website.

26.4 Configuring Mobility Features

Some of the tasks you perform to create the Mobility infrastructure are activating the device repository, configuring device groups, creating custom filters for device groups.

See these topics:

26.4.1 How to Activate Your Device Repository

To activate your device repository:

  1. In the Admin interface, open the General Admin tree, then expand the Mobility node, and then double-click Device Repository.
  2. In the Device Repository Uploader form, upload either the default repository (devices.xml) or the WURFL repository (WURFL.zip, or wurfl.xml and its current patch file).

    Note:

    When you switch the device repository, you are reminded to update the device names that you changed in devices.xml, across all device groups.

    The WURFL.patch file is used with the WURFL.xml file, regardless of the record for WURFL.patch in the device repository table which is still set to Active=F (false).

    Figure 26-5 Device Repository Uploader Form

    Description of Figure 26-5 follows
    Description of "Figure 26-5 Device Repository Uploader Form"
  3. Click the Save icon.

26.4.2 How to Configure the Device Repository

You have the option to use one of the following device repositories: devices.xml (default repository) or WURFL.

  • To use devices.xml, do the following:

    1. Ensure the file contains the device names and user agents you require. Locate the file in the DeviceRepository directory and make the necessary changes.

    2. Activate devices.xml by uploading to WebCenter Sites.

      1. Open the General Admin tree, expand the Mobility node, and then double-click Device Repository.

      2. In the Device Repository Uploader form, upload devices.xml, and then save.

  • To support more capabilities and devices than currently registered in the devices.xml file, use WURFL as the device repository. Do the following:

    1. Obtain the WURFL repository in one of the following 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/.

        Note:

        WURFL is a third-party device repository. You must purchase a license from ScientiaMobile to use this repository. It is not included with WebCenter Sites.

    2. To use the wurfl.xml file and patch, configure the patch file before you continue to other steps.

    3. Activate the WURFL repository by uploading to WebCenter Sites.

26.4.3 How to Create Custom Filters for Device Group Criteria

WebCenter Sites provides a default custom filter implementation (DefaultCustomFilter.java), which takes an XML file as input. To create a custom filter of your own, write an implementation of the CustomDeviceFilter.java interface. The XML file for a custom filter is uploaded from the Device Group configuration page, as described in How to Configure Device Groups.

This section includes the following:

Note:

For information about how to use custom filters, see How to Configure Device Groups.

26.4.3.1 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.

The following example shows a sample filter XML in which device property names are taken from the 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. The default device repository (devices.xml) XML looks something like the following example (notice that the property names have changed). In this filter XML, there are two filters: tabletFilter and flashFilter.

<?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).

26.4.3.2 Creating Your Own DeviceGroupFilter Implementation

The following example shows a Java class that implements the DeviceGroupFilter interface 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.

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

26.4.4 How to Configure Device Groups

To configure a device group:

  1. Under the Mobility node, expand the Device Groups node.

  2. Click Add Device Group, as shown in this figure:

    Figure 26-6 Add Device Group

    Description of Figure 26-6 follows
    Description of "Figure 26-6 Add Device Group"

    The Device Group form opens.

  3. 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. Or, choose an existing suffix if there is any.

      Note:

      This suffix is not editable. 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 no longer used in device detection.

  4. Select the Criteria tab (see the next figure) to create a set of rules for matching real devices so they can be associated with their correct template variants.

    Either provide one or more device names (the rest of the form will be disabled (see the figure below), or omit the device name(s) and fill in the rest of the form.

    Figure 26-7 Add Device Names

    Description of Figure 26-7 follows
    Description of "Figure 26-7 Add Device Names"
    1. If you choose to enter device name(s), enter the same name(s) that are registered in the device repository. If you uploaded devices.xml, enter the device entry name. If you uploaded WURFL, enter the model_name of the device.

      The Device Names field provides Typeahead feature so you can choose a registered device name from the list of available devices. As you start typing a device model number, this features shows all the registered devices beginning with the common letters. You can easily scroll and choose from the first 50 devices. To see more devices, please refine your search further.

      A device can belong to only one device group at a given time.

    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, 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, 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, use the substring iPhone, which matches all iPhones.

        Note:

        To see how many devices for the user agent you entered are available in your device repository, click the Refresh icon in the Matching Devices section.

      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, to match this device group to only Tablet devices that do not support JavaScript, select Yes for the IsTablet capability; 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, a maximum width of 640 will match this device group to all devices whose screen resolution width is 640 or less.

      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.

  5. 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 (as shown in the next figure).

    Figure 26-8 New Device Group

    Description of Figure 26-8 follows
    Description of "Figure 26-8 New Device Group"

26.4.5 How to Prioritize Device Groups

You must prioritize multiple device groups to enable device detection which automatically associates a real device to the highest-priority device group at runtime.

To prioritize device groups:

  1. Under the Mobility node, expand the Device Groups node.
  2. Double-click Reorder Device Groups .

    Figure 26-9 Reorder Device Groups

    Description of Figure 26-9 follows
    Description of "Figure 26-9 Reorder Device Groups"
  3. On the Reorder Device Groups page, drag and drop the device groups in the order of your preferred priority.

    Figure 26-10 Drag and Drop Device Groups

    Description of Figure 26-10 follows
    Description of "Figure 26-10 Drag and Drop Device Groups"

    When you have reordered the device groups, the Reorder Device Groups page displays them in the new sequence (such as the one in the figure below).

    Figure 26-11 Device Groups Reordered

    Description of Figure 26-11 follows
    Description of "Figure 26-11 Device Groups Reordered"
  4. Click Save Priority.

    The Device Groups have been re-prioritized successfully message is displayed.

    Once you have prioritized your device groups and created the device assets, verify that device groups and assets are correctly associated by device detection. Open the device group and select the Devices tab to view the list of device assets associated with the device group.

26.4.6 How to Create Device Assets

To create a device asset:

  1. Under the Mobility node, expand the Devices node.

  2. Click Add Device .

    The Device form opens.

    Figure 26-13 Device Form - Content Tab

    Description of Figure 26-13 follows
    Description of "Figure 26-13 Device Form - Content Tab"
  3. On the Content tab:

    1. In the Name field, enter a name for this device asset.

      This name 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 the real device that this device asset represents. This field is used in device detection logic to associate a 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 option to make this device asset available to device detection mechanism so this asset can be associated to device groups.

    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 to 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.

  4. 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.

    • Height: Height of display area within the device image in which you’ll preview your site content.

    • Width: Width of display area within the device image in which you’ll preview your site content.

    • Top: Top margin for display area within the device image in which you’ll preview your site content.

    • Left: Left margin for display area within the device image in which you’ll preview your site content.

    • Pixel Ratio: Ratio between physical pixels and logical pixels. For instance, iPhone 7 has a pixel ratio of 2 because the physical linear resolution is double the logical linear resolution.

    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 26-14 Screen Dimensions Tab

    Description of Figure 26-14 follows
    Description of "Figure 26-14 Screen Dimensions Tab"
  5. Click the Save icon on the form to create the new device.

    The success message is displayed.

26.4.7 How to Create Site Navigations

Whether you need multiple site navigations or a single site navigation depends on your design approach. When creating a site navigation, you will associate device groups to this navigation by selecting a common suffix. Once selected, that suffix is no longer available for other site navigations.

To create a site navigation:

  1. In the Admin interface, open the General Admin tree, expand the Admin node, then the Sites node, and then the site for which you are creating the site navigation.
  2. Expand the Site Navigations node.
  3. Double-click Add New .

    Figure 26-15 Site Navigations Node in the Admin Tab

    Description of Figure 26-15 follows
    Description of "Figure 26-15 Site Navigations Node in the Admin Tab"

    The Add Site Navigation form opens.

  4. In the Name field, enter a meaningful name for your site navigation.
  5. (Optional) In the Description field, enter a description for your site navigation.
  6. To associate device groups with this site navigation, 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 navigations.

    The Associated Device Groups panel lists the device groups that are associated with your selected suffix.

    Figure 26-16 Associated Device Group Panel

    Description of Figure 26-16 follows
    Description of "Figure 26-16 Associated Device Group Panel"
  7. Add a meaningful icon to your site navigation to help content contributors identify whether the pages opened in Web or Form mode belong to this particular site navigation. This feature is quite useful when working with multiple site navigations. To add an icon, next to the Icon field, click Browse, then navigate to the directory in which the icon is located. The recommended icon image size is 16 pixels * 16 pixels.

    In the Contributor interface, this icon will appear on left of the site navigation and of its pages when they are opened in Web or Form modes. For example, see this figure:

    Figure 26-17 Site Navigation Icon

    This image shows the Site Navigation icon.
  8. Click Add to complete the site navigation.

    A page similar to this figure opens.

    Figure 26-18 New Site Navigation Created

    Description of Figure 26-18 follows
    Description of "Figure 26-18 New Site Navigation Created"
  9. Click the Site Navigation tab to see the newly created site navigation.

    To modify the site navigation, double-click it under your site's node on the Admin tab. On the Modify Site Navigation page, make the changes and then click Modify.

26.4.8 How to Organize Site Navigations

Reorder site navigations to display them in a specific order in the Admin and Contributor interfaces.

To organize site navigation:

  1. In the Admin interface, under the General Admin tab, expand the Admin node, and then expand the Sites node and the site for which you are prioritizing the site navigations.

    Note:

    If you are assigned the SiteAdmin role, use the Site Admin tab instead.

  2. Under Site Navigations, double-click Reorder Site Navigations.

    Figure 26-19 Reorder Site Navigations

    Description of Figure 26-19 follows
    Description of "Figure 26-19 Reorder Site Navigations"
  3. On the Reorder Site Navigations page, drag and drop site navigations to order them in the preferred sequence.

    Figure 26-20 Drag and Drag Site Navigations

    Description of Figure 26-20 follows
    Description of "Figure 26-20 Drag and Drag Site Navigations"

    When you have reordered the site navigations, the Reorder Site Navigations page looks something like this figure.

    Figure 26-21 Site Navigations Reordered

    Description of Figure 26-21 follows
    Description of "Figure 26-21 Site Navigations Reordered"
  4. Click Save.

    The Modification was successful message is displayed.

26.5 Mirror Publishing the Device Repository to Delivery System

After you’ve configured the infrastructure for your mobile site, remember to mirror publish the device repository to the delivery system.

Note:

After modifying and mirroring a device repository, you can trigger the reassociation of devices with device groups on the target system by opening a device group for editing and saving it without necessarily changing any values.

To mirror publish the WURFL device repository:

  1. Under the Mobility node, double-click the Device Repository node.
  2. In the Device Uploader screen, under WURFL, select the Single Zip upload option and upload the wurfl.zip file.
  3. Click the Mirror icon located next to the Save icon.

    The available destination options are displayed.

    The destinations that are up and running have the Green icon, and those that are not running currently, show the Red icon. When a destination's icon is Red, the check box is disabled.

  4. Select the check box for the desired destination option.

    Note:

    Before performing the next step, ensure that WURFL.jar is already available on the destination machine. Mirroring the WURFL device repository without placing a copy of the WURFL.jar on the delivery system prevents the device groups from functioning properly.

  5. Click Mirror.

    The chosen device repository is mirrored to the selected destination. A success message is displayed.

    The selected destination's indicator turns Grey after the repository is mirrored.

26.6 Creating Templates

You can create just one set of templates that works for all mobile device or different sets using the suffix feature of WebCenter Sites.

So, 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 this second approach.

See these topics:

26.6.1 Basic Guidelines for Creating Template Variants

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

  1. Create the base template (the template that renders the desktop website).

  2. Create the template variant by using the name of the base template and appending _suffix.

  3. Use the suffix (the d parameter) as one of the cache criteria to cache pages based on your templates.

26.6.2 Understanding Mobility Tags

The table below describes the Mobility tags you will use when creating templates. See the Oracle Fusion Middleware Tag Reference for Oracle WebCenter Sites Reference.

Table 26-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. The code in the tag is executed if the device supports this capability.

<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")%>] />

Use the device:siteplan tag to look up the site navigation 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 navigation with the same suffix and to return the ID of that site navigation. The site navigation ID is used by other tags to construct website navigation.

26.6.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 How Device Detection Works.

26.6.4 Creating Template Variants

You create the template variants by copying, modifying, and adding a suffix to base templates. This suffix feature lets you create both, a single template variant and template variants in bulk for suffixes for which no variants exist.

This section includes the following topics:

Note:

Suffix-based search lets you easily locate templates of a certain suffix. That is, click Search on the menu bar and then choose Find Template from the Search table. On the Search for: Templates screen, choose Suffix from the Search drop-down list and the desired suffix from the for drop-down list. The search results also include deactivated or deleted templates. (Remove these templates from your site so they do not show up in search results again.)

26.6.4.1 How to Create a Variant of a Single Template

To create a template variant:

  1. Determine if a variant of a template already exists. Navigate to the template's Inspect mode's Template Variants section.

    The View link is displayed under the Action column if a template variant exists for a particular suffix, otherwise the Create link is displayed.

    Figure 26-22 Template Variants

    Description of Figure 26-22 follows
    Description of "Figure 26-22 Template Variants"
  2. To create a variant of a template, click the Create link.

    The Template form is displayed.

  3. Perform Name and Describe the Template Asset of Creating Template, CSElement, and SiteEntry Assets.

26.6.4.2 How to Create Template Variants in Bulk

To create template variants of multiple templates:

  1. On the Dev tab, expand Template, then double-click Bulk Copy Templates.
  2. On the Bulk Copy Templates page, choose the required suffix from the Suffix drop-down list.
  3. In the Asset Types box, select an asset whose templates you wish to copy.

    This displays the associated base templates in the Available Base Templates (n) box.

  4. Select the templates you wish to copy. Choose one, many, or all templates displayed in the Available Base Templates box, as required.

    The Selected Base Templates box is populated with the chosen templates.

    Figure 26-24 Bulk Copy Templates

    Description of Figure 26-24 follows
    Description of "Figure 26-24 Bulk Copy Templates"
  5. Click Generate.

    The Successfully Generated templates: <name> message is displayed.

26.7 Optimizing Images for Mobile Websites

The image optimization filter lets you optimize images for your mobile websites.

You can also plug in your own image optimization implementation to optimize images in a custom way. The following sections discuss both these approaches:

26.7.1 How to Optimize Images Using the Image Optimization Filter

The image optimization feature of WebCenter Sites is available for flex asset families. You can optimize full-size images to display them suitably on various types of mobile devices. This feature enables you to optimize images for different suffixes to support different screen dimensions. For instance, on some devices, the images displayed should be 50% of the full-size images, whereas on other devices, images should be displayed even smaller than 50% of the actual size.

To optimize images using the image optimization filter:

26.7.1.1 Create a Flex Filter of the ImageOptimizationFilter Type

  1. On the menu bar, click New.
  2. From the list of options, click New Filter.

    The New Filter form is displayed.

  3. In the Name field, enter a name for your new filter.
  4. From the Filter dropdown list, choose ImageOptimizationFilter, then click Get Arguments.

    Figure 26-25 ImageOptimizationFilter

    This image shows the Filter dialog.
  5. Under the Arguments section, in the Value field, enter the name of the existing blob type attribute asset for your site. For example, for the avisports sample site, this asset is imageFile and flex family is content. Click Add to apply this value.
  6. Click the Save icon.

26.7.1.2 Include the Filter in Your Site's Image Definition

Include the filter you created in step 1 in the image definition for your site (For example, in the avisports sample site, you can search for Image definition) by performing the following steps:

  1. Open the Image definition for editing.
  2. In the Attributes section, under Available, select your flex family, and click Required. In avisports, the flex family is already selected.
  3. In the Filters section, under Available, select the image optimization filter created in the previous step (myImageOptimizationFilter in our example), and click Select.

    Figure 26-26 Image Definition

    This image shows the Image Definition dialog.
  4. Click the Save icon.

26.7.1.3 Create Instances of the blob Type Attribute Asset

In WebCenter Sites, both single-valued and multi-valued blob type attributes are supported. To apply the image optimization filter to all template variants, create as many instances of the blob type attribute asset as there are suffixes for your site. For example, in avisports sample site, the existing blob type attribute is imageFile. So, in this case, create an instance of this attribute asset for the Touch suffix and another for the NonTouch suffix:

  1. On the menu bar, click New.
  2. From the list of options, click New Attribute.

    The New Attribute form is displayed.

  3. In the Name field, enter a name in format <blob_attribute_name>_<Suffix>. So, for avisports site, it would be imageFile_Touch and imageFile_NonTouch.
  4. From the Attribute Type dropdown list, choose blob.
  5. Click the Save icon.

26.7.1.4 Set Image Properties for Optimization

  1. Under the Mobility tab, double-click Image Properties node.
  2. For the required suffixes, set the following properties:
    • preferredFormats: Optional property. Different types of image formats. For example, for avisports site, for both Touch and NonTouch suffixes, the formats are: jpg,png,bmp,gif. The purpose of various formats is to get the smallest image. The formats are provided in the order of priority. If the first format jpg can give an optimized image, then this format is used. Otherwise, the format with next priority is used. In some cases where none of the supported formats may be helpful in achieving the required size, the full-size image is rendered on devices.

      When omitted, the format of the optimized image is the same as the original/full size image.

    • targetSize: The average size of images on devices. This must be in percentage. For example, 40% of the full-size image.

    • maxsize: The maximum size of images on devices. This must be in percentage. For example, 50% of the full-size image. The optimized image that exceeds the maxsize is not stored as a rendition. If the size (in bytes) of the optimized image exceeds maxSize, the main image is used.

26.7.1.5 Apply the Image Optimization Filter on Existing Images

The image optimization filter comes into play when an image is created or edited. So, to apply this filter on existing images, they must be edited and saved.

  1. Open the images in Edit mode.
  2. Click the Save icon to apply the filter.

26.7.1.6 Verify If the Image Optimization Filter Has Been Applied

  1. Open the Contributor interface.
  2. Search and open an image.

    The Content tab of the image contains a thumbnail for each suffix. The figure below shows the Content tab of a sample image with three thumbnails: one for a full-size image (for the Default site), one for Touch suffix, and one for NonTouch suffix.

    Figure 26-27 Sample Image Content

    This image shows a sample image.
  3. To view the optimized image for each suffix, click the respective URLs available on the URL tab.

    Figure 26-28 Sample Image's URLs

    This image shows the sample image’s URLs.

26.7.1.7 Use the Optimized Images in Your Site

  1. Set the optimize attribute of the render:getbloburl tag to true (<render:getbloburl c=... cid=.. optimize='true' />). See Property Files Reference for Oracle WebCenter Sites.

26.7.2 How to Optimize Images Using a Pluggable Interface

To optimize images for your mobile websites, plug in a custom implementation of the image optimization API, ImageOptimizer.java, as follows:

  1. Create a class that extends abstract class ImageOptimizer.java. For example, see the default implementation of the ImagePercentScaler.java class included in WebCenter Sites: com.fatwire.mobility.image.impl.ImagePercentScaler.
  2. Optionally, create a class that extends the abstract class TargetImageProperties.java. For example, see the default implementation of the DefaultTargetImageProperties.java class included in WebCenter Sites: com.fatwire.mobility.image.impl.DefaultTargetImageProperties. Or, reuse the existing default implementation class itself if properties other than those allowed in default implementation are not used.

    Note:

    If you use the default target properties, do not change the first line in the XML snippet shown in step 3.

  3. In the MobilityService.xml configuration file located at <WebCenter Sites_HOME>/config/, replace the value of the attribute class with the respective implementation of the TargetImageProperties.java and ImageOptimizer.java abstract classes (COM.FutureTense.Mobility.Image.ImageOptimizer and COM.FutureTense.Mobility.Image.TargetImageProperties).
    <bean id="TargetImageProperties" class="com.fatwire.mobility.image.impl.DefaultTargetImageProperties" singleton="false"/>
    <bean id="ImageOptimizationService" class="com.fatwire.mobility.image.impl.ImagePercentScaler" singleton="true" >
           <constructor-arg ref="TargetImageProperties"/>
    </bean>
    

    Now you are ready to use your implementation. For a similar implementation, see the following code:

    ImageOptimizer srv = ServiceLocator.getService( "ImageOptimizationService", ImageOptimizer.class );
    TargetImageProperties targetImageProperties = srv.getTargetImageProperties();
     targetImageProperties.putAll( customPropertnValues );
     //'customPropertnValues' is a map that contains custom property names and values as required by userimplementation ofimageoptimization API
    

26.8 How Device Detection Works

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, it finds the site navigation and invokes the template variant to render the content.

The detailed steps are as follows:

  1. Remote Satellite Server receives a page request from a real device. The header for this request includes the user agent of the device.

  2. 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.

  3. 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 looks for 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.

  4. Remote Satellite Server caches the page and sends the response back to the device.

  5. 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.