Class s7sdk.set.MediaSet
The MediaSet component retrieves an image set definition from Image Serving and parses the set into a DOM-like
structure whose elements describe the set. The component is compatible only with Image Serving versions that support req=set command,
4.7 and higher. After the image serving response arrives and is parsed, a notification event is sent that contains either the root
MediaSetDesc instance representing the set or OrientationSetDesc instance with two nested MediaSetDesc objects. This component supports both mixed media and embedded sets, and ordinary sets. When
using MediaSet to get the set definition, propagating the set definition to the components that support sets must be done from JavaScript
using the provided API.
enableOrientation modifier is set to 0, component returns single MediaSetDesc instance
with AssetEvent.NOTF_SET_PARSED event. This mode of operation is the most common and suitable for applications which
do not change when device is rotated. However certain implementations like eCatalogs may need to present asset differently in different
orientation modes. For example, double-page catalog spreads may appear as a single double-page frame in landscape orientation but show
as two separate single-page frames in portrait orientation. For such applications enableOrientation modifier should be
set to 1, this instructs MediaSet component to return OrientationSetDesc instance with two nested
orientation-specific MediaSetDesc objects. Application code and SDK components may choose which MediaSetDesc
to use depending on device orientation.
MediaSet can override labels for MediaSetDesc elements using MediaSet.LABEL_XX[_YY] and
MediaSet.LABEL_DELIM symbols. In order to override label for a given spread MediaSet.LABEL_XX symbol should be
defined, where XX stands for 0-based item index, applicable for landscape-specific MediaSetDesc. There is no need to
define labels for landscape and portrait orientations separately; it is enough to set landscape-specific labels and MediaSet
will properly apply them to the portrait mode. For example, in order to set labels for the 2nd spread in the catalog,
MediaSet.LABEL_1 should be defined. If MediaSetDesc instance is eCatalog with multi-page spreads, it is possible to
assign label to a specific page inside a spread by adding _YY part to the symbol name, where YY means 0-based
page index inside the spread. For example, in order to set label for the right page of the 3d spread in the catalog,
MediaSet.LABEL_2_1 should be defined. Item labels coming from Image Serving are ignored for a specific
MediaSetDesc item if there is a localization symbol defined for that item or for a page inside that item.
It is important to understand that this component does not recursively extract the definition of the embedded sets. Instead you should react to the current state in the viewer and
explicitly set the desired set using provided setMediaSet() API.
Customizing Behavior Using Modifiers
Modifiers change MediaSet default behavior. They are passed to the component by the ParameterManager instance
specified in the constructor.
The following modifiers are supported:
| Modifier | Syntax | Description | Default |
| serverurl | isRootPath | Image Serving root path. If no domain is specified, the domain from which the viewer is served is used. | /is/image/ |
| contenturl | contentRootPath | The content root path. If no domain is specified, the domain from which the page is served is applied instead. Standard URI path resolution applies. | /is/content/ |
| direction | auto|left|right | Specifies the way the name field of ImageDesc instances used inside the MediaSetDesc is composed in case images consistst of multiple sub-images, like with some eCatalogs. left stitches sub-images in a left-to-right rendering order and right reverses the order so that sub-images are stitched right-to-left. When auto is set, the component applies right mode when locale is set to "ja". Otherwise, left is used. | auto |
| enableOrientation | 1|0 | Defines how the req=set response from Image Serving is parsed. When set to 0, only landscape MediaSetDesc instance representing the set is sent with the AssetEvent.NOTF_SET_PARSED event. When set to 1 the OrientationSetDesc instance with both landscape and portrait MediaSetDesc objects are created. | 0 |
| flattenSets | 0|1[,0|1] | Set the first option to 1 to flatten the media set so that all items from the nested image and swatch sets appear directly in the media set. Use 0 to keep the media set structure unchanged. If the second option is set to 1 then swatches that are explicitly set for items in the nested image and swatch sets are ignored and image thumbnails are used instead. This option applies only when the media set is flattened. | 0,0 |
| asset | isCommand | IS catalog/image ID with an optional IS command. For complicated asset values, use the CopyUrl function to safely generate the asset values. URL-encode template variables within asset values, including Unicode text. URL-encode the entire asset value one time further before using it in a URL. | |
| labelkey | key | Specifies the name of the property that is stored in catalog::UserData which, in turn, defines the text string to use as an image or swatch label. If specified, it is propagated to Image Serving by appending labelkey=key to the req=set request. If the user data property with the specified key is found, Image Serving inserts its value in the response as image and swatch labels. | label |
Localizable Symbols
MediaSet also has two text symbols that you can localize either in a preset or in the viewer page though the mechanisms
provided by the ParameterManager. For more information on localization consult the ParameterManager
API documentation and HTML5 Viewers SDK User Guide.
| Symbol | Description |
MediaSet.LABEL_XX[_YY] | Define a localized label for MediaSetDesc item. XX stands for 0-based item index in landscape orientation; optional _YY part is a 0-based index of a page within multi-page spread. |
MediaSet.LABEL_DELIM | Define a localized delimiter for multi-page labels generated based on MediaSet.LABEL_XX[_YY] symbol. By default is " - ". |
| Constructor Attributes | Constructor Name and Description |
|---|---|
|
s7sdk.set.MediaSet(containerId, settings, compId)
|
| Method Attributes | Method Name and Description |
|---|---|
|
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the
MediaSet component. |
|
|
dispose()
Disposes the component.
|
|
|
setAsset(asset)
Sets the asset directly.
|
|
|
setModifier(modObj)
Sets 1-N # of modifiers for the component.
|
Example Code
This example demonstrates how to use the MediaSet component in a simple viewer. In this example a Container object,
a Swatches object, a ZoomView object, a MediaSet object, and 4 pan button objects are created. The Swatches object
loads and displays all the swatch images in the designated MediaSet. If a user clicks on a swatch the ZoomView object
loads and displays the appropriate image asset. When a user zooms in on the image in the ZoomView, clicking any of
the pan buttons will move the image in the appropriate direction within the ZoomView display area.
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.
- CSS Styles are defined in the document head to control the appearance of the SDK components used in the viewer.
- 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 modifier (hard coded for example purposes),
then creates the component objects required for this simple example. The setAsset() method is called on the
MediaSet object to designate a media set for the viewer to load and display. The initViewer() function also adds
event listeners that designate functions to handle relevant component events (which might be dispatched by the
components as a result of user interactions, changes in a component's state, etc.).
- Handler functions are defined to respond to the component event listeners added in the initViewer() function.
- 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>MediaSet and Pan Button 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.Button');
s7sdk.Util.lib.include('s7sdk.common.Container');
s7sdk.Util.lib.include('s7sdk.set.MediaSet');
s7sdk.Util.lib.include('s7sdk.set.Swatches');
s7sdk.Util.lib.include('s7sdk.image.ZoomView');
</script>
<style type="text/css" media="screen">
.s7zoomview {
width: 300px;
height: 300px;
}
.s7panupbutton {
display:block;
position: absolute;
top: 30px;
left: 25px;
width: 25px;
height: 25px;
z-index: 5000;
}
.s7pandownbutton {
display:block;
position: absolute;
top: 80px;
left: 25px;
width: 25px;
height: 25px;
z-index: 5000;
}
.s7panleftbutton {
display:block;
position: absolute;
top: 55px;
left: 0px;
width: 25px;
height: 25px;
z-index: 5000;
}
.s7panrightbutton {
display:block;
position: absolute;
top: 55px;
left: 50px;
width: 25px;
height: 25px;
z-index: 5000;
}
.s7swatches {
top: 305px;
left: 0px;
height: 150px;
width: 300px;
border: 1px;
border-color:#cccccc;
background-color: rgba(200, 200, 200, 0.5);
}
</style>
</head>
<body>
<div id="s7container"></div>
<script language="JavaScript" type="text/javascript">
var params, container, swatches, zoomView, mediaSet,
panRightButton, panLeftButton, panUpButton, panDownButton;
// Initialize the SDK
s7sdk.Util.init();
// Create ParameterManager instance to handles modifiers
params = new s7sdk.ParameterManager();
// Define the function that initializes the viewer
function initViewer(){
// Set hardcoded modifiers (not required when values are specified on the url)
params.push("serverurl", "http://s7d1.scene7.com/is/image");
// Create the container component object
container = new s7sdk.Container(null, params, "s7container");
// Note: Any component supporting the setMediaSet API can be driven
// by the MediaSet component.
// Create the Swatches component object
swatches = new s7sdk.set.Swatches(container, params, "swatches");
// Create the ZoomView component object
zoomView = new s7sdk.image.ZoomView(container, params, "zoomView");
// Create the pan button component objects
panRightButton = new s7sdk.common.PanRightButton(container, params, "panRightButton");
panLeftButton = new s7sdk.common.PanLeftButton(container, params, "panLeftButton");
panUpButton = new s7sdk.common.PanUpButton(container, params, "panUpButton");
panDownButton = new s7sdk.common.PanDownButton(container, params, "panDownButton");
// Create the MediaSet component object
// Note: The MediaSet constructor does not require the first or last parameter
mediaSet = new s7sdk.set.MediaSet(null, params, null);
// Note: MediaSet.setAsset can be called any time after the MediaSet is created.
// The NOTF_SET_PARSED event will be sent each time a new asset is loaded.
mediaSet.setAsset('demo/Backpacks');
// Add event listeners for pan button clicks
panUpButton.addEventListener("click",function(){zoomView.zoomNPan(0, 0.2);}, true);
panDownButton.addEventListener("click",function(){zoomView.zoomNPan(0, -0.2);}, true);
panLeftButton.addEventListener("click",function(){zoomView.zoomNPan(0.2, 0);}, true);
panRightButton.addEventListener("click",function(){zoomView.zoomNPan(-0.2, 0);}, true);
// Add an event listener for mediaset parsed events
// Note: This event will be emitted every time the MediaSet.setAsset function is called.
mediaSet.addEventListener(s7sdk.event.AssetEvent.NOTF_SET_PARSED, onSetParsed, false);
// Add an event listener for swatch selected events
swatches.addEventListener(s7sdk.AssetEvent.SWATCH_SELECTED_EVENT, onSwatchSelected, false);
// Add an event listener for zoom capability state changes
zoomView.addEventListener(s7sdk.event.CapabilityStateEvent.NOTF_ZOOM_CAPABILITY_STATE, onZoomStateChange);
}
// Define an event handler function to update the swatches when the mediaset is parsed
function onSetParsed(event) {
swatches.setMediaSet(event.s7event.asset);
swatches.selectSwatch(0);
}
// Define an event handler function to update the ZoomView image when a new swatch is selected
function onSwatchSelected(event){
zoomView.setItem(event.s7event.asset);
}
// Define an event handler function to enable/disable pan buttons based on zoom state
function onZoomStateChange(event){
if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.PAN_LEFT)){
panLeftButton.activate();
}else{
panLeftButton.deactivate();
}
if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.PAN_RIGHT)){
panRightButton.activate();
}else{
panRightButton.deactivate();
}
if(event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.PAN_UP)){
panUpButton.activate();
}else{
panUpButton.deactivate();
}
if (event.s7event.state.hasCapability(s7sdk.ZoomCapabilityState.PAN_DOWN)){
panDownButton.activate();
}else{
panDownButton.deactivate();
}
}
// 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} containerId
- Not used for MediaSet.
- {s7sdk.ParameterManager} settings
- A ParameterManager object that contains all settings.
- {String} compId
- Not used for MediaSet.
MediaSet component. The handler function
receives a DOM event object of type Event. The object contains a property s7event,
which references the associated custom event object, for example s7sdk.event.AssetEvent.
The event supported by the component is:
s7sdk.event.AssetEvent.NOTF_SET_PARSED - Dispatched when image serving response arrives and is parsed. s7sdk.event.AssetEvent- Parameters:
- {String} type
- Event name, for example
s7sdk.event.AssetEvent.NOTF_SET_PARSED. - {Function} handler
- Function to be called when the event gets dispatched.
- {Boolean} useCapture
- Register capture phase.
s7sdk.event.AssetEvent.NOTF_SET_PARSED
event is emitted with the parsed DOM structure in the AssetEvent.asset
property in the s7event object, passed to the s7sdk.event.AssetEvent.NOTF_SET_PARSED event
handler.
- Parameters:
- {String} asset
- The asset string that identifies the media set, or any other Scene7 Publishing System asset.
- Parameters:
- {Object} modObj
- A simple JSON object with name:value pairs of valid modifiers for a particular component