.

docs/index.rst

@@ -22,6 +22,7 @@ The complete solution for managing your research data.
    Development Environment </software-developer-documentation/development-environment/index>
    APIS </software-developer-documentation/apis/index>
    Server-Side Extensions </software-developer-documentation/server-side-extensions/index>
+   Client-Side Extensions </software-developer-documentation/client-side-extensions/index>
 
 User Documentation
 ^^^^^^^^^^^^^^^^^^
@@ -35,7 +36,7 @@ Software Developer Documentation
    - :doc:`Development Environment </software-developer-documentation/development-environment/index>`
    - :doc:`APIS </software-developer-documentation/apis/index>`
    - :doc:`Server-Side Extensions </software-developer-documentation/server-side-extensions/index>`
-   - Client-side Extensions
+   - :doc:`Client-Side Extensions </software-developer-documentation/client-side-extensions/index>`
    - Legacy Server-side Extensions
    
 System Admin Documentation

docs/software-developer-documentation/client-side-extensions/eln-lims-web-ui-extensions.md

+ELN-LIMS WEB UI extensions
+==========================
+
+## Introduction
+
+The current aim of this extensions is to accommodate two groups of
+modifications:
+
+Pure Configuration, enabling/disabling some features, to clean the
+interface and make it less confusing for non expert users. Very often
+also to add type extensions for types specified with another master data
+extension.
+
+extending the interface to accommodate additional functionality without
+needing to deal with the internals.
+
+## Plugin structure
+
+![image info](img/128.png)
+
+### plugins folder
+
+Each folder on this folder is a ELN UI extension.
+
+Each extension currently contains a single file with name "plugin.js".
+
+### config.js file
+
+Contains a section called  PLUGINS\_CONFIGURATION indicating the plugins
+to be loaded from the plugins folder.
+
+    var PLUGINS_CONFIGURATION = {
+        extraPlugins : ["life-sciences", "flow", "microscopy"]
+    }
+
+### plugin.js file
+
+Contains the actual source of the plugin, we can distinguish three clear
+sections/patterns on the skeleton of the interface:
+
+-   Interface:
+    <https://sissource.ethz.ch/sispub/openbis/-/blob/master/ui-eln-lims/src/core-plugins/eln-lims/1/as/webapps/eln-lims/html/js/config/ELNLIMSPlugin.js>
+
+1. Configuring views through the use of a JSON structure. Part of this
+structure are:
+
+-   forcedDisableRTF (Deprecated in favour of Custom Widgets
+    configurable from the Instance Settings on the UI)
+-   forceMonospaceFont (Deprecated in favour of Custom Widgets
+    configurable from the Instance Settings on the UI)
+-   experimentTypeDefinitionsExtension
+-   sampleTypeDefinitionsExtension
+-   dataSetTypeDefinitionsExtension
+
+These are used extensively since they come at a very low development
+effort. Best examples of how to use these definition extensions can be
+found in technologies that ship with the ELN:
+
+-   Generic Technology:
+    <https://sissource.ethz.ch/sispub/openbis/-/blob/master/ui-eln-lims/src/core-plugins/eln-lims/1/as/webapps/eln-lims/html/plugins/generic/plugin.js>
+-   Life Sciences Technology:
+    <https://sissource.ethz.ch/sispub/openbis/-/blob/master/ui-eln-lims/src/core-plugins/eln-lims/1/as/webapps/eln-lims/html/plugins/life-sciences/plugin.js>
+
+2\. Extending views through the use of the [Interceptor
+Pattern](https://en.wikipedia.org/wiki/Interceptor_pattern)
+
+-   Template Methods: **ONLY** allow to add content in certain portions
+    of the Interface. **ONLY** available for Experiment, Sample and
+    DataSet form views. These template methods are easy to use, they
+    allow to add custom components isolating the programmer from the
+    rest of the form.
+    -   experimentFormTop
+    -   experimentFormBottom
+    -   sampleFormTop
+    -   dataSetFormBottom
+    -   dataSetFormTop
+    -   dataSetFormBottom
+-   Event Listeners: Allow to listen the before/after paint events for
+    **ALL** form views and list views. Allow the programmer to change
+    the model before is displayed and any part of the view after.
+    Provide versatility but with added complexity of dealing with the
+    complete form.
+    -   beforeViewPaint
+    -   afterViewPaint
+
+&nbsp;
+
+-   Template methods are only needed to add custom components to from
+    views. Best examples of how to use these can be found in
+    technologies that ship with the ELN:
+    -   Microscopy Technology:
+        <https://sissource.ethz.ch/sispub/openbis/-/blob/master/ui-eln-lims/src/core-plugins/eln-lims/1/as/webapps/eln-lims/html/plugins/microscopy/plugin.js> 
+
+3\. Other Extensions:
+
+-   onSampleSave: Reserved for internal use and discouraged to use. It
+    is tricky to use properly.
+-   getExtraUtilities: Allows to extend the utilities menu. A great
+    example is this template:
+    <https://sissource.ethz.ch/sispub/openbis/-/blob/master/ui-eln-lims/src/core-plugins/eln-lims/1/as/webapps/eln-lims/html/plugins/template-extra-utilities/plugin.js>
+
+## Source Code Examples (plugin.js)
+
+### Configuration Only Extensions
+
+An example with only type configurations extensions is show below.
+
+    function MyTechnology() {
+       this.init();
+    }
+
+    $.extend(MyTechnology.prototype, ELNLIMSPlugin.prototype, {
+       init: function() {
+       
+       },
+       experimentTypeDefinitionsExtension : {
+            "FOLDER": {
+                "TOOLBAR": { CREATE: false, FREEZE: false, EDIT: false, MOVE: false, DELETE: false, UPLOAD_DATASET: false, UPLOAD_DATASET_HELPER: false, EXPORT_ALL: false, EXPORT_METADATA: true }
+            }
+       },
+       sampleTypeDefinitionsExtension : {
+            "SAMPLE_TYPE" : {
+                "TOOLBAR": { CREATE : true, EDIT : true, FREEZE : true, MOVE : true, COPY: true, DELETE : true, PRINT: true, HIERARCHY_GRAPH : true, HIERARCHY_TABLE : true, UPLOAD_DATASET : true, UPLOAD_DATASET_HELPER : true, EXPORT_ALL : true, EXPORT_METADATA : true, TEMPLATES : true, BARCODE : true },
+                "SHOW" : false,
+                "SAMPLE_CHILDREN_DISABLED": false,
+                "SAMPLE_CHILDREN_ANY_TYPE_DISABLED" : false,
+                "SAMPLE_PARENTS_DISABLED": false,
+                "SAMPLE_PARENTS_ANY_TYPE_DISABLED": true,
+                "SAMPLE_PARENTS_HINT": [{
+                    "LABEL": "Parent Label",
+                    "TYPE": "PARENT_TYPE",
+                    "ANNOTATION_PROPERTIES": []
+                }],
+                "SAMPLE_CHILDREN_HINT" : [{
+                    "LABEL": "Children Label",
+                    "TYPE": "CHILDREN_TYPE",
+                    "MIN_COUNT" : 0,
+                    "ANNOTATION_PROPERTIES": [{"TYPE" : "ANNOTATION.SYSTEM.COMMENTS", "MANDATORY" : false }]
+                }],
+                "ENABLE_STORAGE" : false,
+                "SHOW_ON_NAV": false,
+                "SHOW_ON_NAV_FOR_PARENT_TYPES": undefined,
+                extraToolbar : undefined
+            },
+       },
+       dataSetTypeDefinitionsExtension : {
+            "DATASET_TYPE" : {
+                "TOOLBAR": { EDIT : true, FREEZE : true, MOVE : true, ARCHIVE : true, DELETE : true, HIERARCHY_TABLE : true, EXPORT_ALL : true, EXPORT_METADATA : true },
+                "DATASET_PARENTS_DISABLED" : false,
+                extraToolbar : undefined
+            },
+       }
+    });
+
+    profile.plugins.push(new MyTechnology());
+
+### Toolbar Extensions
+
+An example with only toolbar extensions is shown below, variables with a
+dollar sign '$' indicate they are jquery components:
+
+    function MyTechnology() {
+       this.init();
+    }
+
+    $.extend(MyTechnology.prototype, ELNLIMSPlugin.prototype, {
+       init: function() {
+       
+       },
+       sampleTypeDefinitionsExtension : {
+            "SAMPLE_TYPE" : {
+                extraToolbar : function(mode, sample) {
+                    var toolbarModel = [];
+                    if(mode === FormMode.VIEW) {
+                        var $demoButton = FormUtil.getButtonWithIcon("glyphicon-heart", function () {
+                            //This empty function could be a call to do something in particular
+                        });
+                        toolbarModel.push({ component : $demoButton, tooltip: "Demo" });
+                    }
+                    return toolbarModel;
+                }
+            },
+       },
+       dataSetTypeDefinitionsExtension : {
+            "DATASET_TYPE" : {
+                extraToolbar : function(mode, dataset) {
+                    var toolbarModel = [];
+                    if(mode === FormMode.VIEW) {
+                        var $demoButton = FormUtil.getButtonWithIcon("glyphicon-heart", function () { 
+                            //This empty function could be a call to do something in particular
+                        });
+                        toolbarModel.push({ component : $demoButton, tooltip: "Demo" });
+                    }
+                    return toolbarModel;
+                }
+            },
+       }
+    });
+
+    profile.plugins.push(new MyTechnology());
+
+### Extra Views as Utilities
+
+Please check the provided example:
+<https://sissource.ethz.ch/sispub/openbis/-/blob/master/ui-eln-lims/src/core-plugins/eln-lims/1/as/webapps/eln-lims/html/plugins/template-extra-utilities/plugin.js>
\ No newline at end of file

docs/software-developer-documentation/client-side-extensions/index.rst

+Client-Side Extensions
+======================
+
+.. toctree::
+   :maxdepth: 4
+
+   eln-lims-web-ui-extensions
+   openbis-webapps
\ No newline at end of file

docs/software-developer-documentation/client-side-extensions/openbis-webapps.md

+openBIS webapps
+===============
+  
+## Introduction
+
+Webapps are HTML5 apps that interact with openBIS. Webapps can be
+distributed as core-plugins. To supply a webapp plugin, create a folder
+called `webapps` in the `as`. Each subfolder of the `webapps` folder is
+treated as a webapp plugin. A webapp plugin requires two things, a
+`plugin.properties` file, as with all plugins, and a folder containing
+the content of the webapp. This folder can have any name and needs to be
+referenced in the `plugin.properties` file with the key
+**webapp-folder**.
+
+It is recommended to name the webapp folder `html` as done in the
+examples below. This has the advantage that an existing subfolder named
+`etc` will not be changed after an upgrade of the plugin. That is, the
+content of the folder `html/etc` will be completely untouched by
+upgrades. This feature allows to provide an initial configuration (say
+in `html/etc/config.js`) with some default settings which can be
+overridden by the customer.
+
+The webapp is then served by the same web server (jetty) that serves
+openBIS. The name of the webapp defines the URL used to access it. See
+the example below. The file index.html is used as a welcome page if the
+user does not specifically request a particular page.
+
+An openBIS webapp is *not* a J2EE webapp. It has more in common with an
+app for mobile devices.
+
+ 
+
+### Example
+
+This is an example of a webapp. In a real webapp, the name of the webapp
+can be any valid folder name. The same goes for the folder in the webapp
+containing the the code. The name of the webapp folder is what is used
+to define the URL. The name of the folder containing the code is neither
+shown nor available to the user.
+
+#### Directory Structure
+
+-   \[module\]  
+    -   \[version\]  
+        -   `as`  
+            -   `webapps`  
+                -   example-webapp  
+                    -   `plugin.properties`
+                    -   html  
+                        -   `index.html`
+                -   fun-viewer  
+                    -   `plugin.properties`
+                    -   html  
+                        -   code
+                        -   `index.html`
+
+#### plugin.properties
+
+    # The properties file for an example webapps plugin
+    # This file has no properties defined because none need to be defined.
+    webapp-folder = html
+
+#### URL
+
+If openBIS is served at the URL <https://my.domain.com:8443/openbis>,
+the above webapps will be available under the following URLs:
+
+-   <https://my.domain.com:8443/openbis/webapp/example-webapp>
+-   <https://my.domain.com:8443/openbis/webapp/fun-viewer>  
+      
+
+Server Configuration
+--------------------
+
+There are two things to consider in the server configuration. The
+injection of webapps is done through Jetty, which is the web server we
+use for openBIS. If you use the default provided jetty.xml
+configuration, then you do not need to do anything extra; if, on the
+other hand, you have a custom jetty.xml configuration, then you will
+need to update your jetty.xml file to support webapps. 
+
+ 
+
+### Jetty Configuration
+
+If your openBIS server has a custom jetty.xml file, you will need to
+modify the file to include support for injecting web apps. To do this,
+you will need to replace
+org.eclipse.jetty.deploy.providers.WebAppProvider by
+ch.systemsx.cisd.openbis.generic.server.util.OpenbisWebAppProvider in
+`addAppProvider` call to your jetty.xml.
+
+**jetty.xml**
+
+    <Call name="addBean">
+      <Arg>
+        <New id="DeploymentManager" class="org.eclipse.jetty.deploy.DeploymentManager">
+          <Set name="contexts">
+            <Ref id="Contexts" />
+          </Set>
+          <Call name="addAppProvider">
+            <Arg>
+              <New class="ch.systemsx.cisd.openbis.generic.server.util.OpenbisWebAppProvider">
+                <Set name="monitoredDir"><Property name="jetty.home" default="." />/webapps</Set>
+                <Set name="scanInterval">0</Set>
+                <Set name="extractWars">true</Set>
+              </New>
+            </Arg>
+          </Call>
+        </New>
+      </Arg>
+    </Call>
+
+Embedding webapps in the OpenBIS UI
+-----------------------------------
+
+#### Introduction
+
+Webapps can be used as both standalone applications as well as can be
+embedded in the OpenBIS web UI. Standalone webapps are built to
+completely replace the original OpenBIS web interface with customer
+adjusted layout and functionality. Users of the standalone webapps are
+usually completely unaware of the default OpenBIS look and feel. The
+webapp itself provides them with all the functionality they need: login
+pages, web forms, searches, images, charts etc. The standalone webapp is
+a right choice when you want to build a very specific and fully featured
+web interface from scratch. If you want to use the default OpenBIS UI
+but extend it with some custom functionality then embedding a webapp in
+the OpenBIS UI is probably a way to go. To make a webapp visible as a
+part of the default OpenBIS UI you have to define where the webapp
+should be shown using "openbisui-contexts" property. Moreover some of
+the contexts also require additional information describing when the
+webapp should be shown. For instance, to embed a webapp in the
+experiment details view that will be displayed for experiments with type
+"MY\_EXPERIMENT\_TYPE" your plugin.properties file should look like:
+
+**plugin.propeties**
+
+    webapp-folder = html
+    openbisui-contexts = experiment-details-view
+    experiment-entity-types = MY_EXPERIMENT_TYPE
+
+#### Configuring embedded webapps
+
+A full list of supported properties is presented below.
+
+|Property Key|Description|Allowed values|
+|--- |--- |--- |
+|openbisui-contexts|Place where the webapp is shown in the OpenBIS UI.|modules-menu
+webapp is an item in the modules top menu
+experiment-details-view
+webapp is a tab in the experiment details view
+requires experiment-entity-types to be defined
+sample-details-view
+webapp is a tab in the sample details view
+requires sample-entity-types to be defined 
+data-set-details-view
+webapp is a tab in the data set details view
+requires data-set-entity-types to be defined 
+material-details-view 
+webapp is a tab in the material details view
+requires material-entity-types to be defined 
+Accepts a comma separated list of values with regular expressions, e.g. "modules-menu, .*-details-view"|
+|label|The label. It will be shown in the GUI.|String|
+|sorting|Sorting of the webapp. Webapps are sorted by "sorting" and "folder name" ascending with nulls last (webapps without sorting are presented last).|Integer|
+|experiment-entity-types|Types of experiments the webapp should be displayed for.|Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"|
+|sample-entity-types|Types of samples the webapp should be displayed for.|Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"|
+|data-set-entity-types|Types of data sets the webapp should be displayed for.|Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"|
+|material-entity-types|Types of materials the webapp should be displayed for.|Accepts a comma separated list of values with regular expressions, e.g. "TYPE_A_1, TYPE_A_2, TYPE_B_.*"|
+
+#### Creating embedded webapps
+
+Embedded webapps similar to the standalone counterparts are HTML5
+applications that interact with OpenBIS. Because embedded webapps are
+shown inside the OpenBIS UI they have access to additional information
+about the context they are displayed in. For instance, a webapp that is
+displayed in the experiment-details-view context knows that it is
+displayed for an experiment entity, with a given type, identifier and
+permid. Having this information the webapp can adjust itself and display
+only data related to the currently chosen entity. Apart from the entity
+details, a webapp also receives a current sessionId that can be used for
+calling OpenBIS JSON RPC services. This way embedded webapps can reuse a
+current session that was created when a user logged in to the OpenBIS
+rather than provide their own login pages for authentication. A sample
+webapp that makes use of this context information is presented below:
+
+**webapp.html**
+
+    <html>
+    <head>
+        <!-- include jquery library required by the openbis.js -->
+        <script src="/openbis/resources/js/jquery.js"></script>
+        <!-- include openbis library to gain access to the openbisWebAppContext and openbis objects -->
+        <script src="/openbis/resources/js/openbis.js"></script>
+    </head>
+    <body>
+
+
+    <div id="log"></div>
+
+
+    <script>
+        $(document).ready(function(){
+
+
+            // create a context object to access the context information
+            var c = new openbisWebAppContext();
+            $("#log").append("SessionId: " + c.getSessionId() + "<br/>");
+            $("#log").append("EntityKind: " + c.getEntityKind() + "<br/>");
+            $("#log").append("EntityType: " + c.getEntityType() + "<br/>");
+            $("#log").append("EntityIdentifier: " + c.getEntityIdentifier() + "<br/>");
+            $("#log").append("EntityPermId: " + c.getEntityPermId() + "<br/>");
+
+
+            // create an OpenBIS facade to call JSON RPC services
+            var o = new openbis();
+
+
+            // reuse the current sessionId that we received in the context for all the facade calls
+            o.useSession(c.getSessionId());
+
+            // call one of the OpenBIS facade methods
+            o.listProjects(function(response){
+                $("#log").append("<br/>Projects:<br/>"); 
+                $.each(response.result, function(index, value){
+                     $("#log").append(value.code + "<br/>");  
+                });
+            });
+        });
+
+    </script>
+    </body>
+    </html>
+
+#### Linking to subtabs of other entity detail views
+
+A link from a webapp to an entity subtab looks like this:
+
+    <a href="#" onclick="window.top.location.hash='#entity=[ENTITY_KIND]&permId=[PERM_ID]&ui-subtab=[SECTION];return false;">Link Text</a>
+
+, for example
+
+    <a href="#" onclick="window.top.location.hash='#entity=EXPERIMENT&permId=20140716095938913-1&ui-subtab=webapp-section_test-webapp;return false;">Experiment webapp</a>
+
+ENTITY\_KIND = 'EXPERIMENT' / 'SAMPLE' / 'DATA\_SET' / 'MATERIAL'
+
+PERM\_ID = Entity permid
+
+SECTION = Subtab identifier.
+
+Notes about subtab identifiers:
+
+-   The valid subtab identifiers can be found from
+    ch.systemsx.cisd.openbis.generic.client.web.client.application.framework.DisplayTypeIDGenerator.java
+-   Managed property subtab identifiers are of format
+    'managed\_property\_section\_\[MANAGED\_PROPERTY\_TYPE\_CODE\]'
+-   Webapp subtab identifiers are of format
+    'webapp-section\_\[WEBAPP\_CODE\]' (webapp code is a name of the
+    webapp core-plugin folder, i.e.
+    \[technology\]/\[version\]/as/webapps/\[WEBAPP\_CODE\])
+
+Cross communication openBIS &gt; DSS
+------------------------------------
+
+### Background
+
+Sometimes is required for a web app started in openBIS to make a call to
+the DSS. This happens often to upload files or navigate datasets between
+others.
+
+Making calls to different domains is forbidden by the web security
+sandbox and a common client side issue.
+
+To make the clients accept the responses without additional
+configuration by the users, the server should set a special header
+"Access-Control-Allow-Origin" on the response when accessing from a
+different domain or port.
+
+### Default Configuration
+
+This is done automatically by the DSS for any requests coming from well
+known openBIS web apps.
+
+A well known openBIS web app is a web app running using the same URL
+configured for openbis on the DSS service.properties.
+
+**DSS service.properties**
+
+    # The URL of the openBIS server
+    server-url = https://sprint-openbis.ethz.ch:8446
+
+Even if the web app is accessible from other URLs, not using the URL
+configured on the DSS service.properties will lead to the DSS not
+recognizing the app.
+
+As a consequence the DSS will not set the necessary header and the
+client will reject the responses.
+
+### Basic Configuration
+
+This is required very often in enterprise environments where the
+reachable openBIS URL is not necessarily the one configured on the DSS
+service.properties.
+
+Is possible to add additional URLS configuring the AS
+service.properties.
+
+**AS service.properties**
+
+    trusted-cross-origin-domains= https://195.176.122.56:8446
+
+The first time the DSS will need to check the valid URLs after a start
+up will contact the AS to retrieve the additional trusted domain list.
+
+### Advanced Configuration
+
+A very typical approach is to run both the AS and DSS on the same port
+using a reverse proxy like Apache or NGNIX. This way the web security
+sandbox is respected. On this case the "Access-Control-Allow-Origin"
+header is unnecessary and will also work out of the box.
+
+Even with this configuration, sometimes happens  that a web app call the
+DSS using an auto detected URL given by openBIS. This auto detected URL
+not necessarily respects your proxy configuration, giving a different
+port or hostname to the DSS.
+
+On this case you will need to solve the problems with one of the methods
+explained above or modify your web app.
+
+Embedding openBIS Grids in Web Apps
+-----------------------------------
+
+Users of openBIS will have encountered the advanced and powerful table
+views used in the application. These views allow for sorting and
+filtering. It is possible to take advantage of these views in custom web
+UIs.
+
+### Requirements
+
+It is possible to use openBIS table views in a web UI when the data for
+the table comes from an aggregation service. The parameters to the
+aggregation service are passed as URL query parameters, thus an
+additional requirement is that all the aggregation service parameters
+can be passed this way. A final requirement is that the web UI be
+exposed as an embedded webapp (this is necessary because of the way
+openBIS keeps track of the user of the system). If these requirements
+are met, then it will be possible to embed an openBIS table view display
+the aggregation service data in a web UI.
+
+### Use
+
+To embed a table view, add an iframe to the web UI. The URL of the
+iframe should have the following form:
+
+    {openbis url}?viewMode=GRID#action=AGGREGATION_SERVICE&serviceKey={aggregation service key}&dss={data store server code}[& gridSettingsId][& gridHeaderText][& service parameters]
+
+Parameters:
+
+|Parameter|Description|Required|
+|--- |--- |--- |
+|serviceKey|An aggregation service that will be used for generating the data for the grid.|true|
+|dss|A code of a data store that will be used for generating the data for the grid.|true|
+|gridSettingsId|An identifier of the grid that will be used for storing the grid settings (visibility of columns, sorting, filters etc.). If not specified then the serviceKey parameter is used.|false|
+|gridHeaderText|A header of the grid. If not specified then the header is not shown.|false|
+
+Example:
+
+[http://localhost:8888/openbis-test/index.html?viewMode=GRID\#action=AGGREGATION\_SERVICE&serviceKey=sp-233&dss=standard&gridSettingsId=myTestGridSettingsId&gridHeaderText=myTestGridHeaderText&name=hello](http://localhost:8888/openbis-test/index.html?viewMode=GRID#action=AGGREGATION_SERVICE&serviceKey=sp-233&dss=standard&name=hello)
+
+Full Example
+
+    <!DOCTYPE html>
+    <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-US" lang="en-US">
+    <head>
+        <meta http-equiv="content-type" content="text/html; charset=utf-8" />
+        <title>Embedded Grid Example</title>
+    </head>
+    <body>
+    <iframe src="http://localhost:8888/openbis-test/index.html?viewMode=GRID#action=AGGREGATION_SERVICE&serviceKey=sp-233&dss=standard&gridSettingsId=myTestGridSettingsId&gridHeaderText=myTestGridHeaderText&name=hello" width="100%" height="95%" style="border: none">
+    </body>
+    </html>
+
+Image Viewer component
+----------------------
+
+Image viewer screenshot:
+
+![image info](img/473.png)
+
+Example usage of the image viewer component:
+
+    <!DOCTYPE html>
+    <html>
+    <head>
+    <meta charset="utf-8">
+    <title>Image Viewer Example</title>
+
+    <link rel="stylesheet" href="/openbis/resources/lib/bootstrap/css/bootstrap.min.css">
+    <link rel="stylesheet" href="/openbis/resources/lib/bootstrap-slider/css/bootstrap-slider.min.css">
+    <link rel="stylesheet" href="/openbis/resources/components/imageviewer/css/image-viewer.css">
+
+    <script type="text/javascript" src="/openbis/resources/config.js"></script>
+    <script type="text/javascript" src="/openbis/resources/require.js"></script>
+
+    </head>
+    <body>
+        <script>
+            
+            // ask for jquery library, openbis-screening facade and the image viewer component
+            require([ "jquery", "openbis-screening", "components/imageviewer/ImageViewerWidget" ], function($, openbis, ImageViewerWidget) {
+
+                $(document).ready(
+                        function() {
+                            var facade = new openbis();
+                            facade.login("admin", "password", function(response) {
+     
+                                // create the image viewer component for the specific data sets
+                                var widget = new ImageViewerWidget(facade, [ "20140513145946659-3284", "20140415140347875-53", "20140429125231346-56",
+                                        "20140429125614418-59", "20140506132344798-146" ]);
+
+
+                                // do the customization once the component is loaded
+                                widget.addLoadListener(function() {
+                                    var view = widget.getDataSetChooserWidget().getView();
+
+
+                                    // example of how to customize a widget
+                                    view.getDataSetText = function(dataSetCode) {
+                                        return "My data set: " + dataSetCode;
+                                    };
+
+
+                                    // example of how to add a change listener to a widget
+                                    widget.getDataSetChooserWidget().addChangeListener(function(event) {
+                                        console.log("data set changed from: " + event.getOldValue() + " to: " + event.getNewValue());
+                                    });
+                                });
+
+
+                                // render the component and add it to the page
+                                $("#container").append(widget.render());
+                            });
+                        });
+            });
+        </script>
+
+        <div id="container" style="padding: 20px"></div>
+
+    </body>
+    </html>
\ No newline at end of file