Page tree
Skip to end of metadata
Go to start of metadata

The Third Light Browser is a tool to help integrate Third Light with your CMS or web management application. It enables web developers and integrators to place a "Fetch Image From Third Light" button into a CMS, mailing list manager or other web tool. Using the button, a user working in your CMS can select a file from Third Light and embed a URL into the web or mail page they are editing so that the file will play or display when the page is opened – without the user having to exit the CMS. As well as embedding published files, you can also edit and crop them to suit the purpose, before embedding the link.

The Third Light Browser is available from IMS v6.0.18 onwards. It is included with all Chorus sites.

Example usage

To insert the Third Light browser into another site, you can use the following example code:

<script type="text/javascript" src="http://your-ims-site/angular/IMS.IframeApp.js"></script>
    <script type="text/javascript" src="http://your-ims-site/angular/IMS.IframeAppOverlay.js"></script>

    <script type="text/javascript">
        function launchCMSBrowser(){
            var app = new IMS.IframeAppOverlay("http://your-ims-site/apps/cmsbrowser/", {
                width: '99%',
                height: '99%',
                options: {
                    theme: "light",
                    metadata: true,
                    revisions: true,
                    cropClasses: [
                    {
                        key: "pic",
                        name: "Landscape",
                        width: 450,
                        height: 330,
                        format: "JPG"

                    },
                    {
                        key: "wide",
                        name: "Wide",
                        width: 400,
                        height: 200,
                        format: "PNG"
                    }
                    ],
                    provideSFFUrl:true
                }
            });
            app.on("cropChosen", function(cropDetails) {
                var url = cropDetails.urlDetails.url;
                var image = document.createElement("img");
                image.src = url;
                image.width = cropDetails.urlDetails.width;
                image.height = cropDetails.urlDetails.height;
                document.getElementById('results').innerHTML = "";
                document.getElementById('results').appendChild(image);
            });
        }

    </script>

<button onclick="launchCMSBrowser()">Fetch Image From IMS</button>
<img id="results" style="display:none"/>

Using the selection

When setting up the CMS browser object, you can add callbacks that are fired when a file has been chosen. This is done using app.on("cropChosen", myFunc);

The cropChosen event has associated details of the file selected. The callback function is passed an object containing keys as follows:

Key

Description

id

The Third Light reference of the selected image

originalWidth

The width in pixels of the selected image

originalHeight

The height in pixels of the selected image

fileRevision

The version number of the selected image

cropDefinition

A hash of details describing the selected crop area

cropClass

The key of the crop class selected (as provided to options.cropClasses)

urlDetails

A hash containing details of the URL to the selected file (only present when provideSFFUrl:true was included in the launch options)

metadata

A hash of metadata for the selected file

Within these, subkeys are defined as follows

Sub-key

Description

cropDefinition.rev

Alias of fileRevision

cropDefinition.width

Width in pixels of the chosen output

cropDefinition.height

Height in pixels of the chosen output

cropDefinition.crop.x

The x-coordinate of the top-left of the chosen crop area (in pixels)

cropDefinition.crop.y

The y-coordinate of the top-left of the chosen crop area (in pixels)

cropDefinition.crop.width

The width of the chosen crop area (in pixels, measured on the original file)

cropDefinition.crop.height

The height of the chosen crop area (in pixels, measured on the original file)

urlDetails.url

A URL to the output file

urlDetails.width

The width of the output file (in pixels)

urlDetails.height

The height of the output file (in pixels)

Supported Options

The CMS browser is usually launched via the IMS.IframeAppOverlay. That wrapper takes arguments as follows:

new IMS.IframeAppOverlay("<URL to widget>", {
 width:"<CSS spec overlay width - e.g. 80%>",
 height:"<CSS spec overlay height - e.g. 80%>",
 options:<object to pass to the CMS browser>
});

The CMS browser supports options as follows:

Key

Description

url

IMS URL to browse - defaults to the same as that passed to the IMS.IframeAppOverlay

theme

A string referring to the theme to load. Currently supported options are "light", "dark" and "blue"

cropClasses

An array of hashes defining the output formats to present

metadata

Boolean, whether to enable the display of metadata in the CMS browser (Off by default)

metadataFields

An optional array of metadata fields to include; defaults to all

metadataLayout

An optional array of hashes, describing an order and content of metadata panels to display. Defaults to the IMS configuration

revisions

Boolean, whether to display revisions other than the currently active one. (Off by default)

provideSFFUrl

Boolean, whether to return a URL to the requested output file. Requires that Secure File Fetch be enabled in the site, and that the user has permission to publish files. (Off by default)

closeOnExport

Boolean, whether to close the widget when the selection is made. Otherwise a final page is displayed containing pertinent details. (On be default)

sessionId

An optional session ID to use (rather than prompting the user to log in, or using their existing session). This is useful in conjunction with server-side API-key session set up to allow auto-login

hideCloseButton

Boolean, whether to suppress the 'Close' button on the widget. (Off by default)

showUnsuitableThumbnails
Boolean, denoting whether to show thumbnails that are unsuitable for any of the available crop classes when browsing. (Off by default)
showUnsuitableCropClasses
Boolean, denoting whether to show unsuitable crop classes in the crop class drop-down when cropping an image. (Off by default)
cropSnapInteger denoting the closeness in relative pixels of a padded image to the crop border that will force a snapping of the image to that border. (30 by default, 0 will disable it)

Defining Crop Classes

The cropClasses key in the options hash contains an array of hashes. Each hash contains keys as follows

Key

Description

key

An identifier for the class. This must be unique across the array. It is not presented to the user, but is provided to the cropChosen callback

name

A label for the class. This is the name displayed to the user of the CMS browser

width

The width (in pixels) for the class

height

The height (in pixels) for the class

format

The output format that you want the image to be ("JPG", "PNG", "GIF", "TIF", or "WEB"). "WEB" is a special choice that will maintain the current image type if it is a GIF, JPG or PNG, or else convert it to a PNG

usePadding
Denotes whether padding is allowed to exist around the image for this crop class

Configuring metadata

When the metadata option is on, the CMS browser offers metadata to users. Without any further configuration, this displays the fields (and panels) configured (see Editing Metadata Fields for more information), restricted by user settings if the Multi-tenant Metadata feature is enabled.

It is possible to use the metadataFields option to restrict the list of metadata fields displayed. Using this approach, each field appears under the same panel as it would in IMS, but only the listed fields are displayed.

When specified, this should be an array of Metadata key names (see the "Mappings" tab of the Customise Metadata Page) - for example ["caption","keywords"].

Alternatively, you may specify the metadataLayout option. This takes an array of hashes, describing the panels and fields to display - overriding panel layouts. This is formatted as follows:

[
  { 
    desc: "Panel A",
    tags: ["caption","keywords"]
  },{
    desc: "Panel B",
    tags: ["otr","exifcreationdate"]
  }
]
  • No labels