Quantum

Custom Web Pages in CatDV

CatDV Server 7.3 introduces the concept of “custom web pages”, within the CatDV Web Client, that allow for much greater levels of customisation than can be achieved using the existing mechanism of workspaces and themes. Custom pages are created using an XML-based Page Description Language that specifies the set of ‘components’ that should appear on the page and how they should be laid out.

Creating a Custom Page

Custom Page Definitions are stored in the CatDV Server database and accessed via the ‘page’ endpoint. The page definitions and any associated resources, such as scripts and stylesheets are administered using the ‘Customisations’ admin page, available from the administration home page in the CatDV web UI.

Clicking the Add button displays a dialog that prompts for a name, a type and the resource text. The name specified will form the URL by which the resource will be accessed. For example if a page definition is created with the name ‘test’ – it would be accessed via the following URL:

/catdv/page/test

Stylesheets and JavaScript resources are served as child URLs. For example a stylesheet called ‘test.css’ and a script called ‘test.js’ would be accessed via the following URLs:

/catdv/page/script/test.js
/catdv/page/css/test.css

This document describes the page definition language and the supported components.

Page Definition Language

The overall structure of the page definition language is as follows:

<page title="title">
    <import>
        <script…/>
        <stylesheet…/>
    </import>
    <models>
        <model…/>
    </models>
    <layout>
        <row…> 
        <column…>
        <panel…>
        etc…
    </layout>
</page>

Top-level Tags

<page>

The <page> tag is the root tag for the page definition document and must be present.

Attributes

title – specifies the title of the page – emitted into the HTML <title> header tag.

<import>

The <import> tag allows the page to include associated scripts and stylesheets. It has no attributes but contains either <script> or <stylesheet> child tags.

<script>

The <script> tag imports a named script resource into the page. The resource will have previously been created in the custom pages admin page. (See “Custom JavaScript” section for more details)

Attributes

name – name of the script to include – as specified when creating the resource.

<stylesheet>

The <stylesheet> tag imports a named stylesheet resource into the page. The resource will have previously been created in the custom pages admin page.

Attributes

name – name of the stylesheet to include – as specified when creating the resource.

<models>/<model>

The <models> tags contain a set <model> child tags that define the set of clip models used by the page. For a description of the model system refer to the Page Data Model section below.

Attributes

type – type of clip mode – either ‘clips’ or ‘selected clip’.

name – name of the model used to reference the model from a UI component that displays the data represented by the model.

init – (type= ‘selected clip’ only) if set to the value ‘param’ - initialises the model based on a clip id present in a URL parameter named ‘id’.

clipID –– (type= ‘selected clip’ only) loads the Clip specified by the ID into the model.

catalog – specifies the name of a catalog to load into the model.

catalogID – specifies the ID of a catalog to load into the model.

cliplist – specifies the name of a clip list to load into the model.

cliplistID – specifies the ID of a clip list to load into the model.

smartFolderI – specifies the name of a smart folder to load into the model.

smartFolderID – specifies the ID of a smart folder to load into the model.

query – specifies a REST-style query whose results will be loaded into the model. e.g. ((clip.status)eq(READY_TO_REVIEW))

sortBy/sortDir – specifies the default sort field and direction (ASC or DESC) of the model.

loadRecentClips – loads the top 500 most recently modified clips

limit – (type= ‘selected clip’ only) limit the number of clips loaded (if set to ‘1’ can be used to load the most recent clip of a set into the player)

<layout>

The <layout> tag is the root tag for layout description that determines the placement of the components on the page. For details of the layout description see the ‘Layout System’ section below.

Attributes

fullPage – if set to ‘true’ indicates that this layout should exactly fit the size of the page – with a set of fixed/resizable panels within it. If not set, or set to ‘false’ it indicates this is a ‘flow’ layout where components flow down the page, which will scroll if the layout extends beyond the bottom.

Layout System

Custom pages support a simple layout system based on rows and columns plus dynamic splitters, as well as the option to completely control the layout of the page via CSS of required. It is also possible to mix and match the two approaches.

Layout can either be fixed “full page” layouts – that exactly fill the browser page – or “flow” layouts that can extend downwards beyond the end of the page – in which case the browser will scroll the page contents. The desired mode is controlled by the ‘fullPage’ attribute on the <layout> tag.

Rows and columns make use of CSS flex-box layout to lay out any child components or panels along either the horizontal (flex-direction: row) or vertical (flex-direction: column). Each component or panel within a row or column can specify a fixed size or will expand to fill the remaining space.

Additionally dynamic horizontal and vertical splitters can be included in the layout to allow the user to resize individual panels within the layout. Splitters can only be used in full page layouts.

All layout elements include optional id and class tags that directly control the id and class of the HTML <div> elements that get rendered to the page. This makes it straightforward to target custom CSS rules at the elements to allow complete control over layout if the simple row/column/splitter model does not provide sufficient control.

Layout Tags

<row>

The <row> tag lays out its child elements along a row. It is rendered as an HTML <div> element with display set to ‘flex’ horizontal flex-direction set to ‘row’.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

<column>

The <column> tag lays out its child elements along a column. It is rendered as an HTML <div> element with display set to ‘flex’ horizontal flex-direction set to ‘column’.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

Attributes on <row> / <column> Children

Layout can be further controlled by setting the following attributes on the immediate child tags of the above row/column containers.

Attributes

size – sets the ‘flex-basis’ and width or height of the element.

shrink – if true sets the ‘flex-shrink’ property to ‘1’ .

grow – if true sets the ‘flex-grow’ property to ‘1’ .

background-color – sets background colour of underlying div (for layout debugging)

<panel>

The <panel> tag is a generic container for other elements. It is rendered as an HTML <div> element.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element.

size – where this element is the child of a row or column element – specifies that this element should be of the specified width (column) or height (row).

Jsclass – name of a JavaScript constructor to call to instantiate a handler for this panel (see Custom JavaScript section for more details)

<hsplitter>

The <hsplitter> renders an adjustable, vertical splitter element between its two children (laid out side by side) that a user can drag to adjust the sizes of the two child elements.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

split – number that specifies the initial position of the splitter as a percentage of the available space

<vsplitter>

The <vsplitter> renders an adjustable, horizontal splitter element between its two children (laid one above the other) that a user can drag to adjust the sizes of the two child elements.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

split – number that specifies the initial position of the splitter as a percentage of the available space

Components

The functionality of the custom page is provided by a set of customisable components that are laid out on the page using the layout system described above.

Component Tags

<heading>

The <heading> tag renders an HTML heading tag. The ‘level’ attribute specifies the heading level (h1, h2 etc..).

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

level – specifies the heading level 1=h1, 2=h2 etc.

<navbar>

The navbar (navigation bar) component is a horizontal or vertical panel that contains a set of navigation bar items specified by its child elements. It supports a number of different item types including links, search box and login control.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

Navigation Bar Child Tags

<section [align=”right”]/> - groups navbar items together – optionally right aligning the group.

<logo/> - displays the logo defined in the current theme.

<login/> - displays the standard login widget that displays the name of the currently logged in user and provides links for logging out and changing password.

<link href=”URL” text=”anchor text” target=”[_blank,_new etc.]”/> - displays the specified ‘text’ as an HTML anchor tag with the specified ‘href’ and ‘target’.

<link-button href=”URL” text=”anchor text” target=”[_blank,_new etc.]”/> - displays the specified ‘text’ as a button that when pressed navigates to the URL specified by ‘href’ and ‘target’.

<search-box/> - displays simple search box.

<advanced-search-link/> - displays a link that pops up the Advanced Search dialog.

<tree-navigator>

The tree navigator component displays a tree control whose root nodes are the top-level CatDV navigation groups – catalogs, smart folders and clip lists. The user can drill down into each section to browse the CatDV database. Clicking on an item updates the currently selected clip model to the selected item.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

clips-model – specifies the name of the “clips model” to update when the user click on a node (see Page Data Model for details).

<media-panel>

The media panel displays an image or video player control that allows the user to view the media associated with the currently selected clip – held by the selected clip model.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

selected-clip-model – specifies the name of the “selected clip model” that determines the clip whose media is displayed.

auto-load – automatically load the player (as opposed to just showing the thumbnail image with overlaid play icon)

auto-play – automatically loads and plays the selected clip.

<details-panel>

The details panel displays details about the currently selected clip in a configurable set of tabs. The tabs displayed are configured in the normal way on the server. If specific tabs are required for the custom page the client in panel set visibility rules can be set to web.custom.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

selected-clip-model – specifies the name of the “selected clip model” that determines the clip whose details are displayed.

<clips-panel>

The clips panel displays the clips from the current ‘clips model’ in a configurable grid or table view. It includes UI controls allowing the user to select the desired view. When the user selects clips from the list the clips-panel updates the specified ‘selected clip model’ with the new selection.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

clips-model – specifies the name of the “clips model” whose clips will be displayed in the view.

selected-clip-model – specifies the name of the “selected clip model” will be updated when the user selects one or more clips in the list.

view-controls – id of a DOM element where the view controls should be placed

view-clip-url – URL to a separate ‘view clip’ page which will be navigated to if the user clicks on a clip in the list.

<clips-view>

The clips-view component displays the clips from the current ‘clips model’ in the specified grid or table view. When the user selects clips from the list the clips-panel updates the specified ‘selected clip model’ with the new selection.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

clips-model – specifies the name of the “clips model” whose clips will be displayed in the view.

selected-clip-model – specifies the name of the “selected clip model” will be updated when the user selects one or more clips in the list.

viewType – [‘grid’, ’list’ or filmstrip’] the type of the view to be used to display the clips.

viewName – the name of the view definition to be used to display the clips.

viewClipUrl – if set specifies a URL that will be navigated to when the user clicks on a clip. In this case multi-select functionality is disabled.

strip – [true or false] - specifies whether or not the clips should be displayed in a single horizontal strip.

<summary-panel>

The summary panel displays selected information about the clip from the current ‘selected clip model’. The details to be displayed are defined by the child tags.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

selected-clip-model – specifies the name of the “selected clip model” that specifies the clip whose details are displayed.

Summary Panel Child Tags

<field id=”field_id” name=”name” [max-len=”none|nnn”][display-as=html|src|text][copy-to-clipboard=true]/> - displays the clip field specified by the field identifier given by the ‘id’ attribute and with the label specified by the ‘name’ attribute. The following optional attributes are also supported:

‘max-len’ - The optional ‘max-len’ attribute controls truncation of the text – set to either a number of characters or ‘none’ to disable truncation.

‘display-as’ - attribute applies to HTML fields only and controls how the HTML is displayed:

‘html’ - displays the HTML directly with all formatting intact. ‘src’ – displays the source code of the html with the tags displayed ‘text’ – displays the text extracted from the HTML with no formatting and no tags

‘copy-to-clipboard’ – if set to true a ‘Copy to Clipboard’ button is displayed next to the field label, which will copy the text of the field to the clip board.

<download-button/> - displays a button that when pressed downloads the current clip to the user’s machine.

<heading level=”[1,2,3 etc.]” text=”heading text”/> - displays the specified ‘text’ as an HTML heading tag with the specified ‘level’.

<link href=”URL” text=”anchor text” target=”[_blank,_new etc.]”/> - displays the specified ‘text’ as an HTML anchor tag with the specified ‘href’ and ‘target’.

<link-button href=”URL” text=”anchor text” target=”[_blank,_new etc.]”/> - displays the specified ‘text’ as a button that when pressed navigates to the URL specified by ‘href’ and ‘target’.

< tabs-panel>

The tabs-panel component displays a set of tabs that allow the user to select between a number of child panels. The tabs to be displayed are defined by the child <tab> elements .

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

Tabs Panel Child Tags

<tab [name=”tab name”][selected=true]/> - specifies the name to be displayed in the tab and also acts as the container tag for the contents of each tab. Options are:

name –tab label. selected – if true this tab should be the initially selected.

<browse-tabs>

The browse tabs component displays a set of tabs that allow the user to browse the database based on a predefined set of queries. Each tab can load either a catalog, smart folder or clip list, or can specify a completely custom query. The tabs to be displayed are defined by the child <tab> elements .

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

clips-model – specifies the name of the “clips model” that will be populated with the selected smart folder.

Browse Tabs Child Tags

<tab [name=”tab name”] [catalogID=”nnn”] [catalog=” name”] [ smartFolderID =”nnn”][ smartFolder=”name”][clipListID=”nnn”] [clipList=”name”] [query=”query”][selected=true]/> - specifies the contents that should be loaded into the associated clips-model. Options are:

name –tab label to use if contents specified by ID rather than name. catalog/catalogID – Catalog specified by either name or ID clipList/clipListID – Clip List specified by either name or ID smartFolder/smartFolderID – Smart Folder specified by either name or ID query – REST-style query to run to populate model selected – if true this tab should be the initially selected on

<filter-panel >

The filter panel displays a set of controls that allow the user to filter and sort the set of clips held by the specified ‘clips model’.

Attributes

id – sets the ‘id’ of the underlying HTML <div> element.

class – sets the ‘class of the underlying HTML <div> element

clips-model – specifies the name of the “clips model” that will be filtered/sorted by the functions on this panel.

Filter Panel Child Tags

<sort-menu> - parent element for a set of <item> tags that specify the contents of the sort menu.

<item name="Newest" field="modifiedDate" dir="desc"> - child of <sort-menu> element. Defines one entry in the sort menu. Specifies display name, field identifier to be sorted by and sort direction [asc or desc]

<html >

The contents of the html tag are raw HTML (strictly speaking XHTML as they must be valid XML) and are output into the final page verbatim.

Page Data Model

A number of these components display information about one or more clip objects. For example the <clips-view> component displays a list of clips thumbnails and the <media-panel> allows the user to view the media associated with a clip and, for video assets, play the clip.

In the CatDV web client these sets of clips are held within a ‘clip model’ or a ‘selected clip model’. Each model holds a collection of clips and is responsible for loading and saving those clips to and from the server as well as notifying interested parties when the clips change.

In many cases it is useful to share these models between components so that actions performed by one component can be reflected by another component. For example – when the user selects a clip in the clip view the media panel should display the selected clip. This is achieved by the clip view and media panel sharing the same selected-clip-model.

Specifically when the user selects a clip in the clip view – the clip view’s associated ‘selected-clip-model’ is updated to with the selected clips. The media panel, which shares the same ‘selected-clip-model’ is notified that the select clip has changed and it displays the new clip.

To allow the models to be shared the page holds a central, named set of models (specified by the top-level <models> tag), and the individual components connect to one of these models by specifying their name in the ‘clips-model’ or ‘selected-clip-model’ attributes.

Custom JavaScript

Custom JavaScripts can be included in the page via the page’s <script> tag. To ensure the page has loaded before any custom JavaScript should define a page load method as follows:

function catdv_onPageLoad(page)
{
	create_project_page = new CreateProjectPage(page);
}

The Custom Page will call this once all components have loaded.

Also the Panel layout item includes a jsclass attribute that allows a JavaScript constructor or class name to be specified. This constructor will be called when the panel is instantiated.

The constructor’s signature should be:

constructor($element: JQuery, page: CustomPage, tag: any)

Where:

$element – is a JQuery object that refers to the panel’s div.

page – is a reference to the CustomPage object for this page (see below)

tag – is a JSON representation of the panel tag itself where each XML attribute is represented as a JSON property. Therefore if any custom XML attributes are included in the panel tag in the page definition –these will be accessible via this object.

Each page has a single ‘CustomPage’ object that implements the following methods:

public getNamedComponent(id: string): Element

This method returns one of the components on the page, given the id of the component. This allows the custom JavaScript to interact with the other components.

public getClipsModel(name: string = "default"): ClipsModel

This method returns one of the global “clips” models given the name. This allows the custom JavaScript to either reload the model, provide a different query or to hook into the various events the model generates.

public getSelectedClipsModell(name: string = "default"): SelectedClipsModel

This method returns one of the global “selected clips” models given the name. This allows the custom JavaScript to either reload the model, provide a different query or to hook into the various events the model generates.

8