Class s7sdk.ParameterManager

The ParameterManager is a special component that is part of the HTML5 Viewers SDK core and as such included in the Utils.js. Most other HTML5 Viewers SDK components are loaded dynamicly instead. The dynamic loading mechanism is enabled by the special utility funciton called s7sdk.Util.lib.include. However, it is the ParameterManager that monitors the loading progress and sends notification, in the form of s7sdk.Event.SDK_READY event, when all needed files have been loaded and it is safe to instantiate components that make up the viewer application.

In addition to dynamic loading of JavaScript files the ParameterManager is also responsible for loading and resovling of components' modifiers. The component modifiers are name=value pairs that in some way modify the default behavior of the components. They can be specified in the URL, a viewer preset created using Scene7 Publishing System or directly entered in the HTML page using push() API. When you specify modifiers in a preset using Scene7 Publishing System, the ParameterManager retrieves the preset information from Scene7 Image Serving. It makes the content available for components to use after they are combined with modifiers that are entered in the URL or directly specified in the page. If the same modifier has been specified in more than one place, it is the ParameterManager that resolves the precedence order. The modifiers that are part of the preset override viewer defaults as specified in the page. The URL modifiers however have the highest priority and will override all other modifiers. To ensure this modifier resolution model you must define your default viewer level modifiers inside the s7sdk.Event.SDK_READY handler.

The modifiers could be global in which case they apply to all components that implement a particular modifier. The modifiers can also be prefixed with either component type in which case they apply to all instances of that type or they can be prefixed by the component id in which case only that particular instance will be affected by the specified modifiers. For example the following modifier MediaSet.asset will only apply to the MediaSet component even though many other components support asset modifier. Consult components modifiers property for the list of supported modifiers for each component.

To assist authoring tools development ParameterManager keeps track of all components that are part of the viewer application. To access the components simply iterate over the array returned by getRegisteredComponents() method. Each component has a public JSON object modifiers that has a list of all supported modifiers by the component as well as the default values and ranges.

This component also loads an external stylesheet that might be assosicated with the application through the style parameter, a preset or specified as the default CSS in the ParamterManager constructor. In general, all HTML5 Viewers SDK components support normal CSS rule specification methods using either embedded rules within a style tag or specified in external files in the link tag. However, if the external stylesheet is specified in the preset or using the style parameter in the URL this styesheet will be loaded last and will override the same rules that have already been processed. The advantage of using the default CSS constructor parametar is that this particular CSS file will be only loaded if no CSS file has been specified either in the preset or using the style parameter.

Another important role of the ParameterManager is the SYMBOL resolution and text localization. Namely, number of components have SYMBOLS that hold text that can be localized by calling setLocalizedTexts() method of ParameterManager and passing a JSON object with localized texts as an argument. For example the FlyoutZoomView component has a tip displayed over the component that hints the user to mouse over the component to zoom in. This particular text is stored in the FlyoutZoomView.TIP_BUBBLE_OVER SYMBOL and can be localized by assigning different text for each supported locale.

Again, to asssit authoring tools development and various IDE integration efforts the ParameterManager provides a convinience API listSymbols() that you can use to get all currently defined SYMBOLS in the application and their resolved values, that is, the viewer defaults. You could also get hold of all SYMBOLS present in the viewer by iterationg over the list returned by getRegisteredComponents() and accessing the symbols JSON object. However, these values are the SDK defaults, not the resolved values that take into account overrides specified in the setLocalizedTexts() or preset.

Customizing Behavior Using Modifiers

Modifiers change ParameterManager default behavior. Modifiers supported by the ParameterManager:

Modifier	Syntax	Description	Default
contenturl	context	The URL path or context to use for static content path resolution, such as external CSS files or video. The context is a relative path that is resolved using standard URI rules against the application domain, or it is an absolute path.	is/content
title	title	The title of the web page in which the viewer is running. If the title is not specified, the original web page title is used.

This component being in charge of the loading of JavaScript files, external CSS files and localization supports a number of parameters that you can also enter in the URL as name=value pairs or specify default values in the ParameterManager constructor. All other components only support modifiers.

Parameters supported by the ParameterManager:

Parameter	Description
config	Catalog ID of the preset as defined using Scene7 Publishing System.
locale	Locale to be applied to all Image Serving requests as well as SYMBOL resolution and `lang` attribute for locale specific skinning. Standard locale values apply.
style	Relative or absolute path to the external CSS to be loaded by the `ParameterManager`. This CSS file will take precdedance over any other rule defined as an embedded style or specified in the external CSS file that is loaded using `link` tag.

Class Summary
Constructor Attributes	Constructor Name and Description
	s7sdk.ParameterManager(config, locale, modifierMap, defaultCSS)

Method Summary
Method Attributes	Method Name and Description
	addEventListener(type, handler, useCapture) Adds an event listener to the instance of the `ParameterManager` component.
	dispose() Disposes the component.
	getRegisteredComponents() Returns a list of all components that are part of the viewer application.
	init() Initializes the `ParameterManager` instance.
	listSymbols() A utility function meant for use by the viewer authoring tools.
	push(key, value) A mechanism to specify modifier defaults directly in the viewer code.
	setDefaultLocalizedTexts(inObj) Sets default localized text for the viewer application.
	setLocalizedTexts(inObj) Sets localized text for the viewer application.
	setViewer(inParams) Specifies information about the viewer.

Class Detail

s7sdk.ParameterManager(config, locale, modifierMap, defaultCSS)

Example Code
This example demonstrates how to use the ParameterManager component in a simple viewer. In this example a Container
object and a FlyoutZoomView object are created. Notice that in the initViewer() method default values are pushed
into the ParameterManager object for the "serverurl" and "asset" modifiers, and that localized text strings are set
in three languages for two tooltip SYMBOLS.
	
The code below does the following:

The Scene7 HTML5 SDK is linked to the page and the required s7sdk components are included in the document head.
The s7sdk.Util.init() method is called to initialize the SDK.
A ParameterManager object is created to handle component modifiers for the viewer.
An initViewer() function is defined. This function initializes a couple of modifiers (hard coded for example purposes),
and sets localized strings to be displayed as tooltips by the FlyoutZoomView component when a user interacts with it.
It then creates the component objects required for this simple example.
An event listener is added to the ParameterManager object that designates the initViewer() function as the handler
to call when the Scene7 SDK is loaded and ready.
Finally, the init() method is called on the ParameterManager object to start the viewer.

<!DOCTYPE html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />        
        <meta name="viewport"
              content="user-scalable=no,height=device-height,width=device-width,initial-scale=1.0,maximum-scale=1.0"/>

        <title>ParameterManager Example</title>

        <!--
        To run this example locally you need to replace this with an absolute SDK path.
        For more information check the HTML5 Viewers SDK User Guide or the examples
        included in the package.
        -->
        <script language="javascript" type="text/javascript"
                src="../js/s7sdk/utils/Utils.js"></script>

        <script language="javascript" type="text/javascript">
            s7sdk.Util.lib.include('s7sdk.common.Container');
            s7sdk.Util.lib.include('s7sdk.image.FlyoutZoomView');
        </script>

        <style type="text/css" media="screen">

        </style>

    </head>
    <body style="margin: 0 0;overflow:hidden;">    

        <script language="JavaScript" type="text/javascript">
            var params, container, flyoutView;

            // Initialize the SDK
            s7sdk.Util.init();

            // Create ParameterManager instance to handles modifiers		
            params = new s7sdk.ParameterManager();
                
            // Define the viewer function to be called when all files have been loaded and modifiers/symbols processed.
            function initViewer() {
                // Assign default values for server and asset to be displayed by the component.
                // Even though these are usually entered in the URL it is convenient to put them
                // in the page while debugging your application.
                params.push("serverurl", "http://s7d1.scene7.com/is/image");
                params.push("asset", "demo/Thibaut_RS");

                // Assign new localized values for SYMBOLS defined by the FlyoutZoomView component.
                params.setLocalizedTexts({
                        "en":{
                            "FlyoutZoomView.TIP_BUBBLE_OVER":"English Button over",
                            "FlyoutZoomView.TIP_BUBBLE_TAP":"English Tap Gesture"
                             },
                         "fr":{
                            "FlyoutZoomView.TIP_BUBBLE_OVER":"Français bouton sur",
                            "FlyoutZoomView.TIP_BUBBLE_TAP":"Geste tap français"
                             },
                         "ja":{
                            "FlyoutZoomView.TIP_BUBBLE_OVER":"日本のボタンの上",
                            "FlyoutZoomView.TIP_BUBBLE_TAP":"日本のタップ ジェスチャ"
                             },
                          defaultLocale: "en"
                      });

                // Create the Container component object
                var container = new s7sdk.Container(null,params,"s7container");

                // Create the FlyoutZoomView component object.
                var flyoutView = new s7sdk.FlyoutZoomView(container, params);
            }

            // The ParameterManager will dispatch SDK_READY when all modifiers have been processed
            // and it is safe to initialize the viewer		
            params.addEventListener(s7sdk.Event.SDK_READY, initViewer, false);

            // Now it is safe to process the modifiers, the callbacks have been defined
            // this will trigger the SDK_READY event
            params.init();
        </script>
        
    </body>
</html>

Parameters:
{String} config: Catalog ID of the preset as defined using Scene7 Publishing System (optional). If nothing is supplied as default, the ParamterManager tries to look for the config paramter in the URL. This should only be supplied in the constructor for debugging purposes. For production casses this parameter should either be ommited or set to null.
{String} locale: Locale string (optional). This value can be overwritten by the locale parameter. When locale has been specified it will affect all aspects of localization: 1. content localization through localized content in Scene7 Publishing System, 2. text localization of the SYMBOLS and 3. CSS localization by setting lang attribute of the HTML elements that represents components to the specified value. For more information on localization consult HTML5 Viewers SDK User Guide.
{JSON} modifierMap: A JSON object with modifier name mapping (optional). This allows for modifier name translation before ParameterManager processes them. You can use this to simplify your URL interface or maybe disable overriding of viewer defaults by mapping the modifier name to a non-existing modifier name. For example, to prevent other components from processing asset modifier and direct it always to the MediaSet component you could use something like this: { "asset" : "MediaSet.asset" }.
{String} defaultCSS: Default CSS (optional). This CSS file will be loaded only if no explicit CSS is defined using style parameter. It is the most efficient way of specifying styling defaults since it reduces loading of unnecessary information as in the case with embeded style rules or external CSS files specified using link tag which are always loaded by the browser.

See:: s7sdk.Util.lib.include

Method Detail

addEventListener(type, handler, useCapture)

Adds an event listener to the instance of the ParameterManager component. The handler function will recieve a standard DOM event object of type Event. The supported events are the following:

s7sdk.Event.SDK_READY - Dispatched when the SDK is fully initialized, all needed JavaScript and external CSS files have been loaded, as well as preset and modifier settings resolved. That is, once this event is dispatched it is safe to instantiate viewers components. That is why the viewer code should always be placed inside the handler function for this event.

Parameters:
{String} type: Event name, for example s7sdk.Event.SDK_READY.
{Function} handler: Function to be called when the event gets dispatched.
{Boolean} useCapture: Register capture phase.

dispose()

Disposes the component.

{Array} getRegisteredComponents()

Returns a list of all components that are part of the viewer application.

Returns:: {Array} A list of all components components instantiated by the viewer.

init()

Initializes the ParameterManager instance. You must always call this function before you instantiate viewer components. Before calling this API, it is important to set up a handler function for the s7sdk.Event.SDK_READY event first to avoid timing issues.

{String} listSymbols()

A utility function meant for use by the viewer authoring tools. It extracts all SYMBOLS defined by components and their default values at the viewer level. That is, the SDK level defaults will be combined with any values specified in the ParameterManager.localizedTexts. For more info on localization check the main class description and HTML5 Viewers SDK User Guide.

Returns:: {String} symbols A list of default SYMBOL values for all viewer components in JSON format.

push(key, value)

A mechanism to specify modifier defaults directly in the viewer code. If the modifier already exists, this call is ignored.

Parameters:
{String} key: Modifier name.
{String} value: Value to assign to the modifier.

setDefaultLocalizedTexts(inObj)

Sets default localized text for the viewer application. This text will be overridden by the same localized text set with setLocalizedTexts() or viewer preset record.

Parameters:
{Object} inObj: JSON object with localization data. Refer to the HTML5 Viewers SDK User Guide and the example for more information about the object's content.

setLocalizedTexts(inObj)

Sets localized text for the viewer application. This text will override the same localized text from defaults and viewer preset record.

Parameters:
{Object} inObj: JSON object with localization data. Refer to the HTML5 Viewers SDK User Guide and the example for more information about the object's content.

setViewer(inParams)

Specifies information about the viewer. You can use this API to customize the viewer version, name and type for tracking purposes.

Parameters:

{String} inParams

A string of the following format:

type,version[,name]

where

The type is the viewer type. The default value is s7_html5_sdk.
The version is the viewer version. The default for version is "unknown".
The name is the viewer name. The default for the name is an auto-detection logic which takes the name of the HTML page without extension.

Namespaces

Classes in s7sdk

Class s7sdk.ParameterManager