Configuring CollectionSpace's User Interface (UI) Layer - An Overview

Not Yet Updated for v5.0

The documentation on this page has NOT yet been updated to describe what's changed in the v5.0 release of CollectionSpace.

 

This document provides an overview of the types of configuration changes you can make in CollectionSpace's User Interface (UI) layer. It also provides basic instructions about where and how you can make such changes.

About CollectionSpace's three layers

A CollectionSpace system has three layers. A simplified overview:

  • The User Interface (UI) layer. This layer runs in a web browser, and is what your users will see on their screens when working with CollectionSpace.
  • The Application layer. This layer consists of compiled code, and runs on your server. It routes and translates data between the UI and Services layers, and orchestrates some complex interactions between those two layers.
  • The Services layer. This layer also consists of compiled code, and runs on your server. It stores and provides data relating to your museum's object and procedural records, via a back-end content management system and databases.

About the User Interface layer

Not Yet Updated for v5.0

The documentation on this page has NOT yet been updated to describe what's changed in the v5.0 release of CollectionSpace.

The User Interface layer consists primarily of:

  • HTML pages
  • CSS stylesheets
  • JavaScript scripts
  • Configuration files (of various types)

By editing any or all of these, you can change many of CollectionSpace's behaviors. Some of these changes can be made exclusively in the UI layer, while others may require corresponding changes in the Application and/or Services layers.

The overlay model for User Interface layer configuration

Not Yet Updated for v5.0

The documentation on this page has NOT yet been updated to describe what's changed in the v5.0 release of CollectionSpace.

The User Interface layer uses an overlay model:

  • By default, the User Interface layer will use the files in its defaults folder.
  • However, if you copy one or more files from the defaults folder to the corresponding locations within your museum's own folder - what CollectionSpace calls your "tenant" folder - modify those files, and then copy ("deploy") your tenant folder (packaged appropriately) to the CollectionSpace server, the User Interface layer will use your modified files instead, overriding the default behavior.

You only need to copy into your tenant folder the specific files you need to modify, to adapt CollectionSpace to the needs of your museum. You'll automatically get the default behavior for any files that you don't copy and modify.

Tip

By browsing the sample Lifesci tenant's folder within CollectionSpace's UI repository, you can find some useful examples of modified UI files.

The folder layout of the User Interface layer

Not Yet Updated for v5.0

The documentation on this page has NOT yet been updated to describe what's changed in the v5.0 release of CollectionSpace.

The User Interface layer consists of the following folders:

  • bundle
    Text labels that appear onscreen for titles, fields, buttons, etc.
  • config
    Configuration of screen (page) layouts and components.
  • css
    CSS stylesheets that affect page look and feel.
  • html
    HTML templates for each of CollectionSpace's pages.
  • images
    Image files that appear on HTML pages.
  • js
    JavaScript source code that significantly affects the behavior of CollectionSpace's pages.
  • lib
    JavaScript library files.

You'll be making most of your configuration changes to files that you copy from the defaults folder's bundle, css, html, and images sub-folders, to the corresponding locations within your tenant folder.

Changing certain advanced behaviors may occasionally require copying and making changes to files in the config and js sub-folders, as well.

Configuring the User Interface layer for your museum

Not Yet Updated for v5.0

The documentation on this page has NOT yet been updated to describe what's changed in the v5.0 release of CollectionSpace.

As described in Configuring CollectionSpace, you will be making your UI configuration changes within a folder for your museum; that is, within the folder for your tenant. A tenant is a space or partition on a CollectionSpace system for your museum or collection, within which you'll make most or all of your changes.

First:

  • You'll need to identify - or make - the folder for your tenant.

After that:

  • Copy the specific files you wish to change, from the defaults folder to the corresponding locations inside the folder for your tenant.

And then repeat the following steps, until you are satisfied with your changes:

  • Make changes to those files.
  • Copy ("deploy") the folder for your tenant, containing all of your modified files, to your CollectionSpace server. (You'll typically do this by typing a command at a shell or command prompt.)
  • Reload the appropriate page(s) in your web browser, to see the effects of your changes. (If necessary, clear the web browser's relevant cache(s).)

Making configuration changes for your museum

Not Yet Updated for v5.0

The documentation on this page has NOT yet been updated to describe what's changed in the v5.0 release of CollectionSpace.

The tenant folder for your museum, within the UI source code tree, is where you'll make nearly all of your configuration changes to adapt CollectionSpace for the needs of your museum.

If you haven't already done so, you'll need to do this - just once:

After doing so:

  • Copy over any files you wish to configure for your museum, from the defaults folder into your tenant folder:
    • From src/main/webapps/defaults
    • To the same (corresponding) location within the folder for your tenant, src/main/webapps/tenants/{mymuseum}, where you will replace {mymuseum} with the actual short name of your museum.

A couple of representative examples of copying defaults files into your tenant folder:

  • To change the logo that appears on the login page:
    Copy the file src/main/webapps/defaults/images/header-logo.png to src/main/webapps/tenants/{mymuseum}/images/header-logo.png. (Depending on how you copy the file, you may first need to create the images directory within your tenant folder.)
  • To change the layout of the fields on the Loan In page:
    Copy the file src/main/webapps/defaults/html/pages/LoaninTemplate.html to src/main/webapps/tenants/{mymuseum}/html/pages/LoaninTemplate.html. (Depending on how you copy the file, you may first need to create the html and html/pages directories within your tenant folder.)

There is also one special case, where you will need to make a slight change to the name of the file you're copying into the folder for your tenant:

  • To change the text labels that appear next to fields - identified by their CSS selectors - on one or more pages:
    Copy the file src/main/webapps/defaults/bundle/core-messages.properties to src/main/webapps/tenants/{mymuseum}/bundle/core-messages.properties-overlay (note that the copied file has -overlay added to the end of its name. (Depending on how you copy the file, you may first need to create the bundle directory within your tenant folder.)
  • Edit the files to make your desired changes. Most files can be edited in a text editor, or if you prefer, in specialized applications for editing HTML, CSS, or JavaScript files. Image files can be replaced outright with your custom images, or edited in an image editor.
  • There is one special case worth noting: the src/main/webapps/tenants/{mymuseum}/bundle/core-messages.properties-overlay file, which configures the text labels that appear next to fields and in many other places on various screens. Unlike other UI layer files, this file's contents are overlaid on top of the default settings in src/main/webapps/defaults/bundle/core-messages.properties, with the contents of your museum's overlay file overriding the defaults. As a result, while it is not required that you do so, it is a best practice to edit this file in a text editor and delete all of the lines for text labels that you don't wish to change from their defaults. (Ideally, only changes or additions to text labels should be present in this file; that way, you can more easily track your changes and migrate them to successive versions of CollectionSpace.) See also How to change the text on the Sign In page.

Copying your changes to the CollectionSpace server

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Unknown macro: {multi-excerpt}

To make your changes "live," you'll need to copy (deploy) them to the CollectionSpace server:

  • At your operating system's shell or command prompt, within the ui folder in which you checked out the UI layer source code (e.g. several levels up from your tenant folder), enter:
    mvn install
    
    This will copy (deploy) your tenant folder, containing all of your modified files, to the appropriate place(s) within the CollectionSpace server folder. (Your tenant folder will be packaged up inside the UI's cspace-ui.war file, and that file, in turn, will be copied into the webapps directory of the server folder.)
  • In most cases, the running CollectionSpace server should reflect the deployed changes automatically. (You may need to clear your web browser's cache(s) to see these changes.)
    • If not, you will need to shut down and restart the servers, following the instructions at [Shutting Down CollectionSpace Servers] and [Starting Up CollectionSpace Servers].

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

  • Reload the appropriate page(s) in your web browser, to see the effects of your changes. (Once again, if necessary, clear your web browser's relevant cache(s).)

(Optional) Copying your changes to the CollectionSpace server with minification and concatenation

Most of the time, when copying (deploying) changes you've made the UI layer, you'll want to perform a regular build as described above. However, if you're completely satisfied with your changes and want to obtain some performance benefit in a production environment, you can build the UI source code with minimization and concatenation enabled. This will minify (remove extraneous whitespace and the like from) the system's various CSS and JavaScript files and concatenate them into a smaller number of files.

Note that doing this type of build involves a trade-off: it also makes debugging the UI layer using web developer tools like Firebug close to impossible. When you're trying out new changes or otherwise need to perform debugging, you'll want to switch back to performing regular builds.

The process of building the UI layer with minification and concatenation enabled is described fully in /wiki/spaces/collectionspace/pages/666273358 You can find other performance-related tweaks in Tuning CollectionSpace for Performance.

See also

Configuring CollectionSpace
Configuring CollectionSpace's Application Layer - An Overview
Tuning CollectionSpace for Performance