HTML5 Viewer SDK API Documentation 

Namespaces


Class Index

Classes in s7sdk.favorites

Class s7sdk.favorites.FavoritesEffect

The FavoritesEffect is an effect component which implements storing, rendering and editing capabilities for "favorites" feature.

FavoritesEffect stores information about favorites in the Local Storage. Favorites collection is unique for particular catalog, company, Image Serving URL and embedding web page location. The feature will not work if Local Storage is disabled on client's system, application may use supportsHTML5Storage() static method to check if storage is avaialble.

Just like other "effect" components FavoritesEffect is attached to main view component and renders avaialble favorite icons on top of the main image.

FavoritesEffect supports three operation modes: FavoritesEffect.MODE_VIEW, where it just renders avaialble favorites on top of main view but does not react to end user's actions; FavoritesEffect.MODE_ADD which adds new favorite icon in place of user's click or tap action and FavoritesEffect.MODE_REMOVE which removes existing favorite if user clicks or taps on it. Operation mode can be changed using setMode() method, effective mode can be found using getMode(). The component automatically reverts to FavoritesEffect.MODE_VIEW operation mode after user has added or removed a favorite.

Every favorite icon added to the catalog is represented by FavoriteDesc instance. The list of all avaialble favorites for this particular asset can be retrieved using getFavorites() method. In addition, the component dipatches FavoritesEvent.FAVORITES_CHANGED event each time the list of favorites changes because of loading new catalog, adding new or removing existing favorite by the end user.

Modifiers change FavoritesEffect default behavior. They are passed to the component by the ParameterManager instance specified in the constructor.

The following modifiers are supported:

ModifierSyntaxDescriptionDefault
expirationdaysNumber of days the collection of favorites will be kept on the client's system before they expire. Every time user visits the catalog and makes some changes to the favorites (like add or remove one) expiration timer is reset.30

Defining the Appearance using CSS

The CSS class for styling the FavoritesEffect is .s7favoriteseffect. You can style these states by adding the state attribute selector to the CSS class. It is recommended that you define common CSS under the main class and only define the necessary distinctions when you use attribute selectors.

CSS ClassAttribute SelectorDescription
.s7favoriteseffectcursortype=[mode_add|mode_remove|mode_view]Defines the appearance of mouse cursior in different operation modes.
.s7icon(None)Defines the appearance of the favorite icons.
.s7tooltip(None)A global class selector that defines appearance for the tooltips. To disable tooltips set the display style to none.

Localized Symbols

FavoritesEffect also has 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.

SymbolDescription
FavoritesEffect.TOOLTIPDefine a localized tooltip of single favorite icon

Class Summary
Constructor Attributes Constructor Name and Description
 
s7sdk.favorites.FavoritesEffect(container, settings, compId)
Field Summary
Field Attributes Field Name and Description
<static>  
s7sdk.favorites.FavoritesEffect.MODE_ADD
component renders existing favorites on the screen, also allows to add new favorite by clicking or tapping in the view
<static>  
s7sdk.favorites.FavoritesEffect.MODE_REMOVE
component renders existing favorites on the screen, also allows to remove existing favorite by clicking or tapping on it.
<static>  
s7sdk.favorites.FavoritesEffect.MODE_VIEW
component only renders favorite icons on the screen and does not react to mouse or touch input
Method Summary
Method Attributes Method Name and Description
 
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the FavoritesEffect component.
 
Add new favorite (or remove from) to the center of the current frame.
 
Dispose is used to remove itself and all sub-elements from the DOM
 
Returns an array with all favorites from all frames available for the current asset.
 
Returns current operation mode (view, add new favorite or remove existing favorite)
 
setCSS(classname, property, value)
Sets a particular CSS class and property on a component
 
setMode(mode)
Sets operation mode (view, add new favorite or remove existing favorite).
 
setModifier(modObj)
Sets 1-N # of modifiers for the component.
<static>  
s7sdk.favorites.FavoritesEffect.supportsHTML5Storage()
Returns true if the underlying system supports HTML5 Storage, false otherwise.
Class Detail
s7sdk.favorites.FavoritesEffect(container, settings, compId)
Example Code

This example demonstrates how to use favorites components in a simple viewer. In this example a PageView, ThumbnailGridView, Swatches and TableOfContents component are put together to construct a simple eCatalog viewer. On top of that, we are adding a set of components to support "favorites" feature: FavoritesMany is added to the top ControlBar with the 3 buttons: AddFavoriteButton, RemoveFavoriteButton and ViewAllFavoritesButton. FavoritesEffect component is attached to PageView to support rendering and editing of favorites. FavoritesView component becomes available when user clicks on ViewAllFavoritesButton button and allows to review all available favorites.

The code below does the following:
  1. The Scene7 HTML5 SDK is linked to the page and the required s7sdk components are included in the document head.
  2. CSS Styles are defined in the document head to control the appearance of the SDK components.
  3. The s7sdk.Util.init() method is called to initialize the SDK.
  4. A ParameterManager object is created to handle component modifiers for the viewer.
  5. An initViewer() function is defined. This function initializes a couple of modifiers (hard coded for example purposes), then creates the component objects required for this simple example. 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.).
  6. Handler functions are defined to respond to the component event listeners added in the initViewer() function.
  7. 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.
  8. 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="width=device-width" /> <title>PageView 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.ControlBar'); s7sdk.Util.lib.include('s7sdk.common.Container'); s7sdk.Util.lib.include('s7sdk.set.MediaSet'); s7sdk.Util.lib.include('s7sdk.set.PageView'); s7sdk.Util.lib.include('s7sdk.set.PageScrubber'); s7sdk.Util.lib.include('s7sdk.set.ThumbnailGridView'); s7sdk.Util.lib.include('s7sdk.set.Swatches'); s7sdk.Util.lib.include('s7sdk.set.TableOfContents'); s7sdk.Util.lib.include('s7sdk.favorites.FavoritesEffect'); s7sdk.Util.lib.include("s7sdk.favorites.FavoritesMenu"); s7sdk.Util.lib.include("s7sdk.favorites.FavoritesView"); </script> <style type="text/css" media="screen"> .s7pageview { height: 480px; width: 640px; top: 40px; left: 20px; position: relative; border: solid 1px #cccccc; } .s7thumbnailgridview { height: 480px; width: 640px; top: 40px; left: 20px; position: absolute; border: solid 1px #cccccc; } .s7controlbar{ position: relative; background-color: #cccccc; top: 5px; left: 20px; width: 640px; position: absolute; z-index: 1; } .s7scrubberswatchesbutton { position: absolute; top: 2px; left: 5px; } .s7thumbnailpagebutton { position: absolute; top: 2px; left: 30px; } .s7tableofcontents { position: absolute; top: 2px; left: 60px; } .s7pagescrubber { height: 55px; width: 640px; top: 540px; left: 0px; position: absolute; z-index:100; } .s7swatches { position: absolute; top: 500px; width: 700px; } .s7favoritesmenu { position: absolute; top: 2px; left: 90px; } .s7favoritesview { position: absolute; top: 40px; left: 20px; width:100px; background-color: rgba(221, 221, 221, 0.5); z-index: 1; } .s7favoritesview .s7swatches { top: 0px; left: 0px; width:100px; } </style> </head> <body> <script type="text/javascript" language="JavaScript"> var params, container, pageView, pageScrubber, controls, scrubberSwatchesBtn, thumbnailPageBtn, gridView, swatches, mediaSet, tableOfContents, favoritesEffect, favoritesMenu, addFavorite, removeFavorite, viewAllFavorites; // Initialize the SDK s7sdk.Util.init(); // Create ParameterManager instance to handles modifiers params = new s7sdk.ParameterManager(null,null,{ "asset" : "MediaSet.asset" }); // 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/"); params.push("MediaSet.asset", "Viewers/eCat-Sample"); params.push("MediaSet.labelkey", "toc"); params.push('FavoritesMenu.bearing', 'fit-vertical'); mediaSet = new s7sdk.set.MediaSet(null, params); mediaSet.addEventListener(s7sdk.event.AssetEvent.NOTF_SET_PARSED, onSetParsed); // Create the Container component object container = new s7sdk.common.Container(null, params, "s7container"); // Create the PageScrubber component object pageScrubber = new s7sdk.set.PageScrubber(container,params,"pagescrubber"); // Create the PageView component object pageView = new s7sdk.set.PageView(container, params, "pageview"); // Create the ThumbnailGridView component object gridView = new s7sdk.set.ThumbnailGridView(container, params, "gridview"); // Create the ControlBar component object controls = new s7sdk.common.ControlBar(container, params, "controls"); // Attach the PageView and GridView objects to the ControlBar controls.attachView(pageView, false); controls.attachView(gridView, false); // Create the ScrubberSwatchesButton component object scrubberSwatchesBtn = new s7sdk.common.ScrubberSwatchesButton("controls", params, "scrubberswatches"); // Create the ThumbnailPageButton component object thumbnailPageBtn = new s7sdk.common.ThumbnailPageButton("controls", params, "thumbnailpage"); tableOfContents = new s7sdk.set.TableOfContents("controls", params, "tableofcontents"); tableOfContents.addEventListener(s7sdk.AssetEvent.ITEM_SELECTED_EVENT, onTableOfContentSelected); // Create the Swatches component object swatches = new s7sdk.set.Swatches(container, params, "swatches"); favoritesEffect = new s7sdk.favorites.FavoritesEffect("pageview", params, "favoritesEffect"); favoritesMenu = new s7sdk.favorites.FavoritesMenu("controls", params,"favoritesMenu"); favoritesView = new s7sdk.favorites.FavoritesView(container, params, "favoritesView"); favoritesView.setCSS(".s7favoritesview", "visibility", "hidden"); favoritesView.resize(favoritesView.getWidth(), pageView.getHeight()); addFavorite = new s7sdk.favorites.AddFavoriteButton("favoritesMenu", params,"addFavoriteBtn"); removeFavorite = new s7sdk.favorites.RemoveFavoriteButton("favoritesMenu", params,"removeFavoriteBtn"); viewAllFavorites = new s7sdk.favorites.ViewAllFavoriteButton("favoritesMenu", params,"vieAllFavoriteBtn"); addFavorite.addEventListener("click",function(event){ removeFavorite.setSelected(false); viewAllFavorites.setSelected(false); favoritesView.hide(); favoritesMenu.hidePanel(); if (addFavorite.isSelected()){ favoritesEffect.setMode(s7sdk.favorites.FavoritesEffect.MODE_ADD);//add }else{ favoritesEffect.setMode(s7sdk.favorites.FavoritesEffect.MODE_VIEW);//vewAll } }); removeFavorite.addEventListener("click",function(event){ addFavorite.setSelected(false); viewAllFavorites.setSelected(false); favoritesView.hide(); favoritesMenu.hidePanel(); if (removeFavorite.isSelected()){ favoritesEffect.setMode(s7sdk.favorites.FavoritesEffect.MODE_REMOVE);//remove }else{ favoritesEffect.setMode(s7sdk.favorites.FavoritesEffect.MODE_VIEW);//vewAll } }); viewAllFavorites.addEventListener("click",function(event){ addFavorite.setSelected(false); removeFavorite.setSelected(false); favoritesEffect.setMode(s7sdk.favorites.FavoritesEffect.MODE_VIEW);//vewAll favoritesMenu.hidePanel(); if (viewAllFavorites.isSelected()){ favoritesView.setFavorites(favoritesEffect.getFavorites()); favoritesView.setCSS(".s7favoritesview", "visibility", "inherit"); favoritesView.show(); favoritesView.resize(favoritesView.getWidth(), pageView.getHeight()); }else{ favoritesView.hide(); } }); // Hide the ThumbnailGridView and Swatches objects by default gridView.setCSS(".s7thumbnailgridview", "visibility", "hidden"); swatches.setCSS(".s7swatches", "visibility", "hidden"); // Add an event listener for PageView selection events pageView.addEventListener(s7sdk.event.AssetEvent.ITEM_SELECTED_EVENT, onPageViewSelected, false); // Add an event listener for ThumbnailGridView swatch selection events gridView.addEventListener(s7sdk.event.AssetEvent.SWATCH_SELECTED_EVENT, onGridViewSwatchSelected, false); // Add an event listener for ScrubberSwatchesButton click events scrubberSwatchesBtn.addEventListener("click", onScrubberSwatchesButton, false); // Add an event listener for ThumbnailPageButton click events thumbnailPageBtn.addEventListener("click", onThumbnailPageButton, false); // Add an event listener for PageScrubber selection events pageScrubber.addEventListener(s7sdk.event.AssetEvent.ITEM_SELECTED_EVENT, onPageScrubberSelected, false); // Add an event listener for Swatches selection events swatches.addEventListener(s7sdk.event.AssetEvent.SWATCH_SELECTED_EVENT, onSwatchSelected, false); // Add an event listener for FavoritesEffect events favoritesEffect.addEventListener(s7sdk.event.FavoritesEvent.FAVORITES_CHANGED, onFavoritesChanged); // Add an event listener for FavoritesView selection events favoritesView.addEventListener(s7sdk.AssetEvent.ITEM_SELECTED_EVENT, onFavoritesViewSwatchSelect); } // Define an event handler function to switch pages for PageView item selections function onPageViewSelected(event){ switchToPage(event); } // Define an event handler function to switch pages for ThumbnailGridView swatch selections function onGridViewSwatchSelected(event){ switchToPage(event); } // Define an event handler function to respond to ScrubberSwatchesButton clicks function onScrubberSwatchesButton(event){ if(scrubberSwatchesBtn.isSelected()){ swatches.setCSS(".s7swatches", "visibility", "inherit"); pageScrubber.setCSS(".s7pagescrubber", "display", "none"); }else{ swatches.setCSS(".s7swatches", "visibility", "hidden"); pageScrubber.setCSS(".s7pagescrubber", "display", "block"); } } // Define an event handler function to respond to ThumbnailGridView clicks function onThumbnailPageButton(event){ if(thumbnailPageBtn.isSelected()){ pageView.setCSS(".s7pageview", "visibility", "hidden"); gridView.setCSS(".s7thumbnailgridview", "visibility", "inherit"); }else{ pageView.setCSS(".s7pageview", "visibility", "inherit"); gridView.setCSS(".s7thumbnailgridview", "visibility", "hidden"); } } // Define an event handler function to switch pages for PageScrubber item selections function onPageScrubberSelected(event){ switchToPage(event) } // Define an event handler function to switch pages for Swatches selections function onSwatchSelected(event){ switchToPage(event) } // Define an event handler function to switch pages for TableOfContent item selections function onTableOfContentSelected(event){ switchToPage(event); } // Define a function to update all components to display the currently selected page function switchToPage(event){ pageView.setCurrentFrameIndex(event.s7event.frame); swatches.selectSwatch(event.s7event.frame); gridView.selectSwatch(event.s7event.frame, true); pageScrubber.setCurrentFrameIndex(event.s7event.frame); tableOfContents.setCurrentFrameIndex(event.s7event.frame); // If the ThumbnailGridView is showing, hide it and deselect the ThumbnailPageButton if(thumbnailPageBtn.isSelected()){ thumbnailPageBtn.setSelected(false); onThumbnailPageButton(); } } function onSetParsed(e) { tableOfContents.setMediaSet(e.s7event.asset); pageView.setMediaSet(e.s7event.asset); gridView.setMediaSet(e.s7event.asset); swatches.setMediaSet(e.s7event.asset); pageScrubber.setMediaSet(e.s7event.asset); favoritesView.setMediaSet(e.s7event.asset); } function onFavoritesViewSwatchSelect(event){ pageView.setCurrentFrameIndex(event.s7event.frame); }; function onFavoritesChanged(event){ var disable = true; var favs = favoritesEffect.getFavorites(); favoritesView.setFavorites(favs); addFavorite.setSelected(false); removeFavorite.setSelected(false); addFavorite.activate(); for(var i=0; i < favs.length; i++){ if (favs[i].frameIdx == pageView.getCurrentFrameIndex()){ disable = false; }; }; if (!disable){ removeFavorite.activate(); }else{ removeFavorite.deactivate(); } if (favs.length > 0) { if (viewAllFavorites.isSelected() && viewAllFavorites.getActivated()){ }else{ viewAllFavorites.activate(); } }else{ viewAllFavorites.setSelected(false); viewAllFavorites.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>
Default styles for FavoritesEffect:

.s7favoriteseffect[cursortype='mode_add'] {
	cursor:crosshair;
 }
.s7favoriteseffect[cursortype='mode_remove'] {
	cursor:not-allowed;
 }
.s7favoriteseffect[cursortype='mode_view'] {
	cursor:default;
 }
.s7favoriteseffect {
	z-index:999;
	cursor:pointer;
	pointer-events:auto;
	user-select:none;
	-ms-user-select:none;
	-moz-user-select:-moz-none;
	-webkit-user-select:none;
	-webkit-tap-highlight-color:rgba(0,0,0,0);
 }
.s7favoriteseffect .s7icon {
	position:absolute;
	height:28px;
	width:28px;
	background-size:100% 100%;
	background-image:url(images/sdk/favoriteseffect_up.png);
	z-index:999;
	pointer-events:auto;
	user-select:none;
	-ms-user-select:none;
	-moz-user-select:-moz-none;
	-webkit-user-select:none;
	-webkit-tap-highlight-color:rgba(0,0,0,0);
 }
Parameters:
{String} container
an ID of the component FavoritesEffect is attached to.
{s7sdk.ParameterManager} settings
A parameter manager instance that represents the desired configuration.
{String} compId
An optional parameter that specifies the ID of the component DOM element.
Field Detail
<static> s7sdk.favorites.FavoritesEffect.MODE_ADD
component renders existing favorites on the screen, also allows to add new favorite by clicking or tapping in the view

<static> s7sdk.favorites.FavoritesEffect.MODE_REMOVE
component renders existing favorites on the screen, also allows to remove existing favorite by clicking or tapping on it.

<static> s7sdk.favorites.FavoritesEffect.MODE_VIEW
component only renders favorite icons on the screen and does not react to mouse or touch input
Method Detail
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the FavoritesEffect 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.FavoritesEvent.

The events supported by the component are:

  • s7sdk.event.FavoritesEvent.FAVORITES_CHANGED - Dispatched when the list of favorites changes because of loading new catalog, adding new or removing existing favorite by the end user. s7sdk.event.FavoritesEvent
  • Parameters:
    {String} type
    Event name, for example s7sdk.event.FavoritesEvent.FAVORITES_CHANGED.
    {Function} handler
    Function to be called when the event gets dispatched.
    {Boolean} useCapture
    Register capture phase.

    addRemoveFavorite()
    Add new favorite (or remove from) to the center of the current frame.

    dispose()
    Dispose is used to remove itself and all sub-elements from the DOM

    {Array} getFavorites()
    Returns an array with all favorites from all frames available for the current asset.
    Returns:
    {Array} Array of FavoriteDesc instances.

    {Number} getMode()
    Returns current operation mode (view, add new favorite or remove existing favorite)
    Returns:
    {Number} one of the following constants: s7sdk.favorites.FavoritesEffect.MODE_VIEW, s7sdk.favorites.FavoritesEffect.MODE_ADD or s7sdk.favorites.FavoritesEffect.MODE_REMOVE.

    setCSS(classname, property, value)
    Sets a particular CSS class and property on a component
    Parameters:
    {String} classname
    The CSS classname to use for this style. i.e. .s7favoriteseffect .s7icon
    {String} property
    The CSS property that is being set. i.e. background-position
    {String} value
    The CSS property value being set. i.e. center

    setMode(mode)
    Sets operation mode (view, add new favorite or remove existing favorite).
    Parameters:
    {Number} mode
    - one of the following constants: s7sdk.favorites.FavoritesEffect.MODE_VIEW, s7sdk.favorites.FavoritesEffect.MODE_ADD or s7sdk.favorites.FavoritesEffect.MODE_REMOVE.

    setModifier(modObj)
    Sets 1-N # of modifiers for the component.
    Parameters:
    {Object} modObj
    A simple JSON object with name:value pairs of valid modifiers for a particular component

    <static> {Boolean} s7sdk.favorites.FavoritesEffect.supportsHTML5Storage()
    Returns true if the underlying system supports HTML5 Storage, false otherwise.
    Returns:
    {Boolean} whether or not underlying system supports HTML5 Storage.

    Documentation generated by JsDoc Toolkit 2.4.0 on Thu Jan 30 2020 16:40:36 GMT+0200 (EET)