BROWSE CATDV SUPPORT MANUALS

The CatDV Web 2 interface is designed to be easy to customise. It is implemented using standard HTML5, CSS3,  JavaScript/JQuery and all the source code is provided as part of the installation. The Web 2 interface makes use of the standard CatDV REST API to access CatDV Server functionality, which is documented here.

Also, through its support for themes, it is possible to completely customise the look of the interface, by simply creating a new theme file.

Theme Support

The CatDV Web 2 interface supports skinning through switchable CSS themes. The standard installation contains a number of example themes that can be used as the basis for building custom themes.

Full customisation of fonts, colours etc of all user interface components is possible by compiling a custom theme. Simple customisation, for example replacing the logo and login page background, can be achieved without recompiling a theme. Both are described on this page.

Both mechanisms need the Web 2 source to be unpacked as follows:

Unpacking the Source Code

The theme files are part of the Web 2 source code which is  shipped as part of the catdv.war file tat can be found inside the CatDV Server installation directory. To access the files you must first unpack the war file by following these steps:

On Mac – open a Terminal window and enter the following commands:

  • cd /usr/local/catdvServer
  • mkdir catdv-web2
  • mv catdv-web2.war catdv-web2/catdv-web2.zip
  • cd catdv-web2
  • unzip catdv-web2.zip
  • rm catdv-web2.zip

On Windows:

  • In Windows Explorer navigate to C:Program FilesSquare BoxCatDV Server
  • Rename catdv-web2.war to catdv-web2.zip
  • Create a new folder called catdv-web2
  • Click on catdv-web2.zip to view the contents of the archive and copy them into the catdv-web2 folder.
  • Delete the catdv-web2.zip files

Note that next time you update CatDV Server you will need to redo these steps and reinstate any custom themes you create, so be sure to backup you custom themes to avoid them being accidentally overwritten.

Reconfiguring the Built-in Web Server

In order to tell the built-in web server to serve the newly unpacked files you need to add the following lines the ‘Other’ field in the Server Config form in the CatDV Server Control Panel.

web.app.url.0=/catdv2
web.app.path.0=$~/catdv2
web.app.url.1=/catdv-web2
web.app.path.1=$~/catdv-web2
web.app.url.2=/websamples
web.app.path.2=$~/websamples

You will need to restart CatDV Server after setting the new values.

Layout of Theme Source

Each sample theme is contained in a separate directory where the folder name determines the theme name. There is also a ‘common’ folder that contain files common to all the themes.

There are three sample themes:

  • default – the default light coloured theme
  • dark – a dark theme with light text
  • custom – an example of a custom colour scheme.

Each theme folder is laid out as follows:

  • css/theme.css – Generated CSS stylesheet for this theme
  • img/login_bg.png – Background image shown on the log in page
  • img/logo-large.png – Large branding image used on front page
  • img/logo-small.png – Smaller branding image used on other pages.
  • img/filmstrip_hole.png – Image used as the sprocket holes in the filmstrip view

Selecting a Theme

The Web 2 interface reads the name of the theme to use from the ‘web2client.theme’ variable, that can be set in the Other field on the Server Config page of the CatDV Server Control Panel. A server restart is required for the change to take effect.

Simple Customisation: Changing the Logo

Navigate to the compiled themes folder:

  • on mac: /usr/local/catdvServer/catdv/themes
  • on Windows: C:Program FilesSquare BoxCatDV Servercatdvthemes

Now copy a base theme folder to create the new theme (for example copy the complete ‘default’ folder to ‘my-new-theme’).

Inside the ‘my-new-theme’ folder will now be:

css
    theme.css
img
    filmstrip_hole.png
    login_bg.png
    logo-large.png
    logo-small.png

To change the logos, replace logo-small.png and logo-large.png with new versions. The default themes have these images with transparent backgrounds so the theme colour scheme shows through.

  • logo-large.png should be within 240 x 120 px
  • logo-small.png should be within 240 x 60 px
  • login_bg.png is repeated vertically and horizontally on the login page, with logo-large shown at the top left

Now in the CatDV control panel update the Web 2 theme using:

web2client.theme = my-new-theme

Restart the CatDV Server and the new branding should appear

Custom Themes

CatDV Web 2 themes are implemented using LESS (http://lesscss.org). The LESS source code can be found in the src/themes folder.

The src/themes folder contins the following sub-folders

  • bootstrap-3.2.0 – Unmodified copy of the LESS source code of the Twitter Bootstrap CSS library on which CatDV themes are based.
  • catdv  – LESS source code for the CatDV-specific styles
  • theme-default  – contains the source the ‘default‘ sample theme.
  • theme-dark – contains the source for the ‘dark‘ sample theme.
  • theme-custom – contains the source for the ‘custom‘ sample theme.

Each theme folder contains three files

  • theme.less – Main file for the theme. References (via include statements) all the source files that make up the theme.
  • fonts.less – Defines the fonts used by the theme (included in theme.less)
  • variables.less – Defines values for all the LESS variables used in the theme.

Creating a New Theme

To create a new theme copy one of the existing theme source folders to a new source folder called theme-xxx where xxx is the name of your theme, and copy one of the existing theme folders (default, dark or custom) to a new folder called just ‘xxx’ to hold the generated theme.

In most cases it will only be necessary to edit the values in ‘variables.less’ to create your new theme, as they give you control over the colors of
all the UI elements using in the interface. However, for more radical changes you can also override styles defined in bootstrap and catdv by
adding new definitions directly into theme.less.

After editing the variables file you then need to compile the LESS source files into CSS. This is achieved using the LESS compiler lessc. Please
refer to (http://lesscss.org/#using-less-command-line-usage) for more details on using the less compiler. You should arrange for the generated theme.css
file to be generated into the appropriate theme folder.

  • To install LESS, first install node.js from here: https://nodejs.org/
  • Then follow the instructions at: http://lesscss.org
  • make a compiled theme folder by copying an existing theme as above for simple customisation: say to “my-compiled-theme”
  • compile your theme using something like:
    /usr/local/bin/lessc theme.less > /usr/local/catdvServer/catdv/themes/my-compiled-theme/css/theme.css
  • Now in the CatDV control panel update the Web 2 theme using:
    web2client.theme = my-compiled-theme
  • restart the CatDV Server

You may also wish to provide your own customised versions of the image files for the logo and login screen background.