Skip to end of metadata
Go to start of metadata

Configuring the CollectionSpace UI currently requires a somewhat daunting level of knowledge, about CollectionSpace's source code repository and its layout; about multi-tenancy and the file overlay model; and about deploying changes into the CollectionSpace server using development tools like Ant and Maven. For the new UI, the goal is to make this process more accessible. It should be possible to jump in with some basic web development skills, and no knowledge of the CollectionSpace source code, build process, or server architecture.



The new CollectionSpace UI can be displayed on any web page. Here's a simple example:

Publish the page to a web server. That's it.

Here's a breakdown: The UI is distributed as a JavaScript file, which is loaded into the page (on line 8). This JS file is a minified bundle – think of it as a binary distribution. There's no need to download, edit, or build source code. When the bundle is loaded, it makes the cspaceUI variable available in the global namespace. cspaceUI is a function, which when called (on line 10), renders the UI into the page – by default, inside the main tag (line 7).

This example loads the JS bundle from the UNPKG CDN. It will always be available there, but UNPKG isn't meant for production use. The bundle will also be shipped with future tarball releases of CollectionSpace, set up to be served from CollectionSpace's tomcat server. You can serve it from there in production, or move it to another web server in your environment. Some HTML pages like the one above will also be shipped with CollectionSpace, as starting points for further customization, or for use as-is. They'll be set up to be served from CollectionSpace's tomcat server as well, but they also can be moved to any other server.

There's also an unminified JavaScript bundle available, cspaceUI.js. This bundle contains verbose warning messages, and is suitable for development use.



Configuration is done by passing options to cspaceUI(). The options are in a state of flux as development of the UI continues, but these are some examples that work today:

Pointing to services on a different host

There's no requirement for the UI to be served from the same server as the services layer. By default, the UI will attempt to connect to the REST API at the same host from which it originated, but it can also be configured with the URL of a remote host (line 12):

This assumes that the services layer at has been configured to accept CORS requests from

Supplying translated/customized messages

A museum may want to replace some UI messages with different text, or translate all of the messages to another language. The message bundle is a configuration option:

Changing the container element

The UI doesn't have to be rendered into the main element. A different container element may be specified by supplying a CSS selector:

Supplying an outer header/footer/sidebar

The UI is rendered into a specific element on the page, leaving anything else that might be on the page undisturbed. This allows you to supply your own headers, footers, sidebars, or other content surrounding the CollectionSpace UI container:

Changing the logo or other styles

A museum may want to replace the CollectionSpace logo with its own, or change other styles. This is easily accomplished with some CSS:

In this example, a class (mymuseum) has been added to the main element into which the UI is rendered (line 12). A CSS rule also has been added, using both that class and the one provided by the UI (lines 6-8). Since that rule's selector is more specific than any that exist in the UI's default stylesheet, it overrides the default styling. There are many other ways to achieve this override – the mymuseum class isn't even necessary, since the selector main .cspace-ui-LoginPage--common would also be more specific than any in the default stylesheet – but this way is nicely readable.

More to come...

As development continues, additional configuration options will become available. This could include: adding and removing record types, replacing the form templates for records, changing the columns in search results, and more.


Use Cases

Some interesting use cases are enabled by this simplified configuration:

  • Split hosting. A CollectionSpace hosting provider might host only the back end services, while a client museum hosts the UI on its own server in its own domain. This allows a museum to hire out the hard parts – JEE server and RDBMS management – to experts, while maintaining local control of UI look and feel.
  • Multi-language support. A single CollectionSpace back end can easily be configured with many front-ends. For example, an HTML page at could be configured to display the CollectionSpace UI in English, while another page at could be configured in French, with both pointing to the same services layer.
  • Role-based UI. Mulitiple front-ends could be configured differently for use by museum staff with different roles, for example, registrars vs. photographers. Differences might include the fields that are displayed in each record type. This would be similar to using "templates" in the current UI, but persistent, and able to reach across multiple record types.
  • Collection-based UI. Museums with disparate collections, e.g. natural history and art, could also configure multiple front-ends, each tailored to a different collection. Again, this might be addressed today with "templates," but the multiple front-end approach is persistent and more comprehensive.

Demo Time!

A live, editable example is on CodePen. You can even log in, and create object records on nightly.