Developer Integration Guide

Overview

This document describes how WebCenter Sites application developers can integrate their site with the Cloudwords-WCS Integration plugin.

 This plugin integrates directly with the WebCenter Sites Contributor Interface.  There is no website runtime dependency, nor is there support for any other user interface (WEM Admin or WebCenter Sites Admin).

 This document therefore addresses the core technical requirements for a multi-lingual website running on WebCenter Sites that can take advantages of the UI features allowed in this plugin.

 This document also addresses plugin configuration extension points, which can be used to alter the behavior of the plugin beyond the capabilities of core configuration.

 

Part 1: Website Requirements 

Overview

The Cloudwords-WCS Integration relies on best practices for working with Multilingual Assets in WebCenter Sites.  Website implementations that do not follow these practices, from which relevant portions are summarized below, are incompatible with this integration.

Assets and Languages

Assets in WebCenter Sites should represent content in a single language.  If content is to be translated into a second language, that implies that a second asset is created.  Thus there is no such concept in WebCenter Sites as a “multi-lingual asset”, because assets must only exist in a single language. 

Some assets, such as configuration assets, some structural assets, or others, may not be associated with a language at all.  Of course such assets would not support any concept of translation.

Tagging Assets with a Locale

In order to tag an asset with a language in WebCenter Sites, a “Locale” is tagged to an asset.  Locales are tagged using special assets in WebCenter Sites called “Dimensions”. Dimensions can represent other concepts besides locales, and so for simplicity, Dimensions pertaining to locales are identified by having their subtype value set to “Locale”.  The name of a Dimension of subtype Locale should correspond to the toString() format of the java.util.Locale object.  This usually takes the form “en_US” with “en” representing the language English, and “US” representing the country USA.  The description of these Dimensions should correspond to the way you would like to see the locale displayed in the WebCenter Sites contributor interface.

Special Note: Some of the WebCenter Sites sample sites do not set the description value of locale dimensions to something that normal business users would understand, and instead leave them set to the value of the name, which is the locale code itself (i.e. en_US).  Changing the description is safe, and should be done when working with the Cloudwords-WCS integration.  It is recommended that the description of the locale be set to the same description used in Cloudwords to identify the same thing.


Dimension names are converted into Cloudwords’ language code format via a simple transformation. It is not recommended that more than one dimension with the same name be present in WebCenter Sites.  This behavior is neither tested nor supported.

Identifying Assets as Translations

When two assets are tagged with different locales, they may be tagged as related to one another using what is called a Dimension Parent. This is done by tagging a DimensionParentRelationship for the dimension group “Locale” (i.e. the Dimension subtype) to each of the assets.  This is usually done automatically in WebCenter Sites when a translation is requested. 

To programmatically set or retrieve the value of the Dimension Parent, simply request the attribute “Dimension-Parent” from an appropriately loaded AssetData object.  The DimensionParentRelationship object is returned in a list.

 Master Assets

 The actual value of the tag corresponding to the Dimension Parent is the AssetId of one of the assets in the relationship.  While the asset selected for this purpose is arbitrary at the outset, once it is chosen, that asset is designated the “Master” asset for the translation relationship.

 This integration relies on this type of relationship between translation assets, as this is the structure employed by the WebCenter Sites user interfaces to identify translations. 

Translation Lookups

WebCenter Sites provides various APIs for looking up translations of assets.  In the user interface, translations are either requested collectively (i.e. all translations of an asset are requested at once), or specifically (i.e. a translation in a particular locale is requested).

API

Details

Java

com.fatwire.mda.DimensionableAssetManager.getRelative()
com.fatwire.mda.DimensionableAssetManager.getRelatives()

JSP

<asset:gettranslations>
<asset:getrelatives>

 

On an actual website, these direct lookup APIs may be used, but more often than not website implementations employ client-specific business logic to look up translations.  This is important, for example, when determining what to display when the desired translation of an asset is not available.

Business rules around which locales are to be used for a given website and exactly how lookup policies should be employed is encapsulated in what are called Dimension Sets and Dimension Filters, respectively. 

 Locales can be associated with a Dimension Set in the advanced user interface by setting them as “Enabled Dimensions” for a Dimension Set.  The Dimension Set will then only operate on Dimensions that are enabled.

 The translation lookup business logic is encapsulated in the Dimension Filter object.  A single Dimension Filter is associated with each Dimension Set.  The creation of custom Dimension Filters is beyond the scope of this integration.

 The Cloudwords-WCS integration makes use of the core internal translation lookup mechanism in order to power the user interface for the integration.  It does not make use of either Dimension Sets or Dimension Filters, and thus there is no requirement that these be set up a particular way or even exist for this plugin to operate.

 Website Runtime Requirements

The Cloudwords-WCS integration imposes no constraints on websites at runtime at all.  Absolutely no code relating to this integration needs to be installed on the WebCenter Sites delivery environment, and no logic is executed. Futhermore not a single artifact relating to the Cloudwords-WCS integration is employed at runtime on a website (with the exception of the assets themselves).

 

Part 2: Plugin Customizations

This integration is designed to support multiple user interface extension points.  Some extension points can be implemented by overriding elements in the WebCenter Sites Contributor Interface infrastructure, while other extension points can be implemented by implementing or overriding the appropriate java classes.

As of version 1.0 of this integration, no extension points or customization points are exposed.  If you would like to request an extension or customization point, please contact Cloudwords.

Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.