HTML5 Viewer SDK API Documentation 

Namespaces


Class Index

Classes in s7sdk.common

Class s7sdk.common.Container

The Container component can be used as a parent component for other UI components that are part of the viewer application. The advantage of using this component as the parent over using just a suitable HTML element like div is the component's ability to be targeted by a preset. It also provides useful resizing mechanisms when the browser changes its size as a result of a window size change or the device orientation change. Finally, Container has an API to bring itself (and all its children) to full screen mode.

The component is resized by the web browser according to web page layout and constrained by the given width, height, min-width, min-height, max-width and max-height CSS properties. width and height (if applicable) CSS properties should be specified in relative units (percentages) in order to let browser scale the component; the size of the component will adjust at run time according to web page layout changes caused by browser page resize, device orientation change or other means.
The aspect ratio of the component can be either fixed or unrestricted, which is determined by the aspect modifier as follows:

Each time the size of the component changes s7sdk.event.ResizeEvent.COMPONENT_RESIZE event is dispatched, communicating the new inner component size to the application. It is expected that application code will process this event and make itself responsive too by adjusting its layout programmatically.

The Container also supports a resize() API that can be used to change the size of the container programmatically. Regardless of the resize mechanism, this component will always dispatch an s7sdk.event.ResizeEvent.COMPONENT_RESIZE event, that the viewer developer can use to adjust the viewer application layout in response to the size change.

In addition, this component will always dispatch an s7sdk.event.ResizeEvent.WINDOW_RESIZE event upon device orientation change or window resizing. The advantage of using this event as opposed to listening to the browser RESIZE event is that it is sent with a slight delay to give the device a chance to find its new size.

The Container provides full screen support. On modern desktop browsers and some smartphones (for example, BlackBerry 10) native browser's full screen will be used; on older browsers the Container will just resize to occupy entire browser window; use supportsNativeFullScreen() in order to identify if native mode is available. Use the requestFullScreen() method to enter full screen mode, cancelFullScreen() to leave full screen mode and isFullScreen() to check whether we are in full screen mode or not. The Container dispatches s7sdk.event.ResizeEvent.FULLSCREEN_RESIZE event when entering or leaving full screen mode.

The component is able to detect the situation when it is removed from the web page layout (normally when Container or one of its parents is removed from DOM using removeChild() API or has display:none style applied). When this happens, the component sends s7sdk.event.ResizeEvent.REMOVED_FROM_LAYOUT event and sets its size to 0 by 0 pixels. When component is added back to layout it sends s7sdk.event.ResizeEvent.ADDED_TO_LAYOUT event and restores its size back to the size corresponding to current web page layout. It is possible to use isInLayout() API to check whether Container is currently added to web page layout. Note that the Container may not be able to detect quick removal from layout and adding back followed one after another (for example, when the component is removed and then added to layout in the same JavaScript function).

Container provides built-in mechanism called "size markers" to simplify implementation of responsive applications with the use of breakpoints. The component monitors its run-time size and changes the current size marker whenever the new size hits certain breakpoint value. There are 3 markers supported: SIZE_MARKER_SMALL, SIZE_MARKER_MEDIUM and SIZE_MARKER_LARGE. Breakpoint values and the type of the size measurement can be configured with sizemarkers modifier. The actual size marker is returned by getSizeMarker() method, in addition s7sdk.event.ResizeEvent.SIZE_MARKER_CHANGED event is dispatched every time new size marker is set.

Customizing Behavior Using Modifiers

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

The following modifiers are supported:

ModifierSyntaxDescriptionDefault
stagesizewidth,heightSize of the Container component. When this modifier is specified the component operates in standard mode. This mode means that it does not handle its resizing in response to a change in window size. If this modifier is not used and the width and height are not specified in the CSS, it is assumed that the component is in pop-up mode. In such case, it resizes itself to fit the screen.
aspectratio0[;ratioN]Configures the aspect ratio of the component. ratio is defined as an array of the width-to-height relations separated by semicolon delimiter.
If more than one ratio is specified, the component calculates aspect ratio of current browser window and choose the closest value from ratio array then uses this value to calculating the explicit height value based on effective runtime width; if only one ratio is defined the component will fix container's aspect ratio to that single ratio and will not take browser window size into account.
If length of ratio is not set, the component does not fix its ratio. Instead, it uses the size set by the web page layout and CSS.
0
sizeMarkersarea|width,smallMediumBreakpoint,mediumLargeBreakpointConfigures the measurement type and breakpoints for size markers. area sets area-based breakpoint measurement, where the breakpoint value means the area (width multiplied by height); width sets width-based breakpoint measurement, where only width is considered. smallMediumBreakpoint sets the breakpoint value between small and medium size marker, mediumLargeBreakpoint is the breakpoint between the medium and the large marker.area,310000,920000

Defining Appearance using CSS

The appearance of the Container component can be defined using CSS rules. All HTML5 Viewer SDK components use class selectors for styling. The body of the Container component can be styled using the .s7container class selector. The styles associated with this class selector will be applied to all instances of the Container component. Particular instances may be styled by prefixing the class rule with the instance #id. For example: styling rules for #myComp.s7container will be applied only to the particular Container instance. For more information on component styling see the HTML5 Viewer SDK User Guide and the default styles section.

CSS ClassAttribute SelectorDescription
.s7containermode=[normal|fullscreen]CSS class to specify styling for the Container component. mode attribute tells whether Container is working in full screen or normal mode.

Localized Symbols

Container 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
Container.LABELDefine a localized "aria-label" of Container

Class Summary
Constructor Attributes Constructor Name and Description
 
s7sdk.common.Container(containerId, settings, compId)
Field Summary
Field Attributes Field Name and Description
<static>  
s7sdk.common.Container.SIZE_MARKER_LARGE
Large size marker.
<static>  
s7sdk.common.Container.SIZE_MARKER_MEDIUM
Medium size marker.
<static>  
s7sdk.common.Container.SIZE_MARKER_NONE
Size marker which indicates that the component is not in page layout.
<static>  
s7sdk.common.Container.SIZE_MARKER_SMALL
Small size marker.
Method Summary
Method Attributes Method Name and Description
 
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the Container component.
 
Leaves full screen mode.
 
Disposes Container and removes it from the DOM if Container does not have any children.
 
focusHandler(event)
 
Gets the reference to the component since the constructor function returns a dynamic wrapper not the component itself.
 
Returns the current inner height of the component.
 
 
Returns current size marker.
 
Returns the current inner width of the component.
 
Returns true if the Container is currently in full screen mode, false otherwise.
 
Returns true if the component is currently a part of the web page lyout, false otherwise.
 
Returns true if Container works in "popup" mode, false otherwise.
 
Enters full screen mode.
 
resize(w, h)
Resize the container to given width/height.
 
setCSS(classname, property, value)
Sets a particular CSS class and property on a component
 
setModifier(modObj)
Sets 1-N # of modifiers for the component.
 
Returns true if the underlying system supports native full screen mode, false otherwise.
Class Detail
s7sdk.common.Container(containerId, settings, compId)
Example Code

This example demonstrates how to use the Container component in a simple viewer. In this example a Container object and a ZoomView object are created. Since this is a pop up viewer, the container will be automatically resized when the window size changes. The ZoomView object takes its initial size from its parent, the Container, which means that it will fill the screen. 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. The s7sdk.Util.init() method is called to initialize the SDK.
  3. A ParameterManager object is created to handle component modifiers for the viewer.
  4. 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 function 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.).
  5. A handler function is defined to respond to the component event listener added in the initViewer() method.
  6. 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.
  7. 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>Container</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.ZoomView'); </script> <style type="text/css" media="screen"> html,body { width: 100%; height: 100%; } body { padding: 0px; margin: 0px; font-size: 12px; background: #FFFFFF; overflow: hidden; } </style> </head> <body> <script language="JavaScript" type="text/javascript"> var params, container, zoomView; // 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"); params.push("asset", "Scene7SharedAssets/ImageSet-Views-Sample"); // Create the viewer Container component object container = new s7sdk.common.Container(null, params, "s7container"); // Create ZoomView component object zoomView = new s7sdk.image.ZoomView(container, params, "myZoomView"); zoomView.resize(container.getWidth(), container.getHeight()); // Add event listener for Container resize events container.addEventListener(s7sdk.event.ResizeEvent.COMPONENT_RESIZE, onResizeViewer, false); } // Define an event handler function to resize the ZoomView when the container size changes function onResizeViewer(event){ zoomView.resize(event.s7event.w, event.s7event.h); } // 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 Container:

.s7container {
	width:100%;
	height:100%;
 }
.s7container .s7innercontainer {
	position:relative;
	left:0px;
	top:0px;
	width:100%;
	height:100%;
 }
.s7container[mode='fullscreen'] {
	z-index:9900;
 }
.s7container .s7innercontainer[mode='fullscreen'] {
	position:absolute;
 }
Parameters:
{String} containerId
The ID of the parent DOM element to which the component is added as a child.
{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.
Returns:
{s7sdk.common.ContainerControl} Returns a dynamic wrapper for this component, which is of type s7sdk.common.ContainerControl. This wrapper is only a proxy that allows dynamic setting of modifiers and CSS properties. All other API calls are forwarded to the core component directly.
Field Detail
<static> s7sdk.common.Container.SIZE_MARKER_LARGE
Large size marker.

<static> s7sdk.common.Container.SIZE_MARKER_MEDIUM
Medium size marker.

<static> s7sdk.common.Container.SIZE_MARKER_NONE
Size marker which indicates that the component is not in page layout.

<static> s7sdk.common.Container.SIZE_MARKER_SMALL
Small size marker.
Method Detail
addEventListener(type, handler, useCapture)
Adds an event listener to the instance of the Container 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.ResizeEvent.

The events supported by the component are:

  • s7sdk.event.ResizeEvent.COMPONENT_RESIZE - Dispatched when container changes its inner size. s7sdk.event.ResizeEvent
  • s7sdk.event.ResizeEvent.WINDOW_RESIZE - Dispatched when windows changes its size or orientation. s7sdk.event.ResizeEvent
  • s7sdk.event.ResizeEvent.FULLSCREEN_RESIZE - Dispatched when component enters or leaves full screen mode. s7sdk.event.ResizeEvent
  • s7sdk.event.ResizeEvent.ADDED_TO_LAYOUT - Dispatched when component is added to the web page lyout. s7sdk.event.ResizeEvent
  • s7sdk.event.ResizeEvent.REMOVED_FROM_LAYOUT - Dispatched when component is removed from the web page lyout. s7sdk.event.ResizeEvent
  • s7sdk.event.ResizeEvent.SIZE_MARKER_CHANGE - Dispatched when effective size marker changes because of resize of adding component to the layout or removing it. s7sdk.event.ResizeEvent
  • Parameters:
    {String} type
    Event name, for example s7sdk.event.ResizeEvent.COMPONENT_RESIZE.
    {Function} handler
    Function to be called when the event gets dispatched.
    {Boolean} useCapture
    Register capture phase.
    See:
    s7sdk.event.ResizeEvent

    cancelFullScreen()
    Leaves full screen mode.

    dispose()
    Disposes Container and removes it from the DOM if Container does not have any children. This method has no effect if Container has at least one child component or DOM element.

    focusHandler(event)
    Parameters:
    event

    {s7sdk.common.Container} getComponent()
    Gets the reference to the component since the constructor function returns a dynamic wrapper not the component itself. You should NEVER store a reference returned by this API call since the component might have been rebuilt since your last call.
    Returns:
    {s7sdk.common.Container} The reference to the core component the caller is a proxy for.

    {Number} getHeight()
    Returns the current inner height of the component.
    Returns:
    {Number} the inner height of the component, in pixels.

    {String} getInnerContainerId()
    Returns:
    {String} Returns an ID of the DOM element children of this Container instance are attached to.

    getSizeMarker()
    Returns current size marker.
    Returns:
    size marker, SIZE_MARKER_LARGE, SIZE_MARKER_MEDIUM, SIZE_MARKER_SMALL or SIZE_MARKER_NONE.

    {Number} getWidth()
    Returns the current inner width of the component.
    Returns:
    {Number} the inner width of the component, in pixels.

    {Boolean} isFullScreen()
    Returns true if the Container is currently in full screen mode, false otherwise.
    Returns:
    {Boolean} whether or not component is in full screen mode.

    {Boolean} isInLayout()
    Returns true if the component is currently a part of the web page lyout, false otherwise. The component may be removed from the web page layout (and thus recieve no sizing) by removing any of its parent elements from the DOM using API like removeChild() or by applying display:none style to any of its parent elements.
    Returns:
    {Boolean} true if the component is currently a part of the web page lyout, false otherwise.

    isPopup()
    Returns true if Container works in "popup" mode, false otherwise. "Popup" mode is the mode where application occupies the whole web page, and there is no other content except Container and other components attached to it.

    requestFullScreen()
    Enters full screen mode. Depending on device capabilities, it will use either native full screen support of web browser or only resize to occupy entire browser window.

    resize(w, h)
    Resize the container to given width/height.
    Parameters:
    {Number} w
    Target width in pixels.
    {Number} h
    Target height in pixels.

    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. .s7container
    {String} property
    The CSS property that is being set. i.e. width
    {String} value
    The CSS property value being set. i.e. 600px

    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

    {Boolean} supportsNativeFullScreen()
    Returns true if the underlying system supports native full screen mode, false otherwise.
    Returns:
    {Boolean} whether or not underlying system supports native full screen.

    Documentation generated by JsDoc Toolkit 2.4.0 on Thu Oct 15 2020 11:59:11 GMT-0000 (UTC)