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:
- Create your new tenant. See Creating your new tenant for detailed instructions.
- Find your tenant folder within the UI source code tree. See Finding your tenant folder for instructions.
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.
- From
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 filesrc/main/webapps/defaults/images/header-logo.png
tosrc/main/webapps/tenants/{mymuseum}/images/header-logo.png
. (Depending on how you copy the file, you may first need to create theimages
directory within your tenant folder.)
- To change the layout of the fields on the Loan In page:
Copy the filesrc/main/webapps/defaults/html/pages/LoaninTemplate.html
tosrc/main/webapps/tenants/{mymuseum}/html/pages/LoaninTemplate.html
. (Depending on how you copy the file, you may first need to create thehtml
andhtml/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 filesrc/main/webapps/defaults/bundle/core-messages.properties
tosrc/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 thebundle
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 insrc/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
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: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'smvn install
cspace-ui.war
file, and that file, in turn, will be copied into thewebapps
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