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:

if aspect modifier is set to a value greater than 0, the component will let web page layout to control its width, while height will be calculated internally based on effective width value and configured aspect ratio. Any height explicitly provided in CSS will be ignored.
The following example sets component to fixed aspect ratio mode, with the aspect ratio value of 4:3. The minimum component size will also be limited to 400 by 300 pixels:
Modifier aspect=1.33
```
 .s7container {
	width : 100%;
	min-width: 400px;
 }
```
if aspect modifier is not set, the component will leave its aspect ratio unrestricted. The browser will be able to control both width and height of the component independently according to CSS rules and web page layout.
This example shows the component which always takes the whole size of the parent element, and limits its minimum size to 50 by 60 pixels:
Modifier aspect is not set
```
 .s7container {
	width: 100%;
	height: 100%;
	min-width: 50px;
	min-height: 60px;
 }
```
It is also possible to fix certain component dimension to a static pixel value, and let browser scale only other dimension. This is an example of component with dynamic width and height set to be always 200 pixels; no minimum size set:
Modifier aspect is not set or set to 0
```
 .s7container {
	width : 100%;
	height : 200px;
 }
```

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:

Modifier	Syntax	Description	Default
stagesize	width,height	Size 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.
aspect	ratio0[;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
sizeMarkers	area\|width,smallMediumBreakpoint,mediumLargeBreakpoint	Configures 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 Class	Attribute Selector	Description
`.s7container`	`mode=[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.

Symbol	Description
`Container.LABEL`	Define 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.
	cancelFullScreen() Leaves full screen mode.
	dispose() Disposes `Container` and removes it from the DOM if `Container` does not have any children.
	focusHandler(event)
	getComponent() Gets the reference to the component since the constructor function returns a dynamic wrapper not the component itself.
	getHeight() Returns the current inner height of the component.
	getInnerContainerId()
	getSizeMarker() Returns current size marker.
	getWidth() Returns the current inner width of the component.
	isFullScreen() Returns `true` if the `Container` is currently in full screen mode, `false` otherwise.
	isInLayout() Returns `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.
	requestFullScreen() 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.
	supportsNativeFullScreen() 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:

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),
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.).
A handler function is defined to respond to the component event listener added in the initViewer() method.
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="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.

Namespaces

Classes in s7sdk.common

Class s7sdk.common.Container