How to add a field

Task Description

This document describes how you can add a field to one of CollectionSpace's standard record types: for a Cataloging, Procedure, or Authority Term record.

This particular document uses the example of adding a text field to a Cataloging record. Related documents - to be added - will describe how to add other types of fields: option list fields, date fields, number fields, autocomplete fields for selecting authority terms, and more.

Extension schemas: where you'll add your field

You'll be adding your new field (or fields) within an extension schema. This gives you complete control over the management of your own set(s) of fields, separately and independently from those that come standard with CollectionSpace.

For each standard record type, CollectionSpace comes with a standard schema (set of fields), known as the common schema. Each common schema generally conforms to the SPECTRUM standard.

If you want, you can then supplement the common schemas by creating one or more additional extension schemas. Each extension schema contains a set of additional fields you want to add to a particular record type, where these fields should (by convention and best practices) be either:

• Pertinent to your community of practice (from anthropology and art history to zoology), and potentially usable (and even collaboratively maintainable) by multiple museums within that community
  or
• Specific to your own museum or collecting institution.

As an illustrative example, you might:

• Add an extension schema to Cataloging records, containing fields specific to describing your museum's objects.
• Add two extension schemas to Acquisition records: one containing fields pertinent to how your community of practice generally handles the process of acquiring objects, and a second containing fields specific to your museum's acquisitions data.
• Add an extension schema to Loan Out records, containing fields specific to your museum's loans data.

Prerequisites

This work requires knowledge of how to:

• Make new directories, copy files, and perform similar tasks in your operating system.
• Run commands at your operating system's command prompt.
• Edit text files.
• Edit HTML files.
• Edit XML files.

In addition, if you have not already done so:

• Create a tenant for your museum. (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 configuration changes.)
  • For details, please see Creating your new tenant
• Read an overview of how to make configuration changes in CollectionSpace's Application (UI) layer.
  • For details, please see Configuring CollectionSpace's Application Layer - An Overview
• Read an overview of how to make configuration changes in CollectionSpace's User Interface (UI) layer.
  • For details, please see Configuring CollectionSpace's User Interface (UI) Layer - An Overview

Layers involved

To carry out this task, you will need to make changes in the following CollectionSpace layer(s):

• Application
• User Interface (UI)

In addition, you will need to run a single command in the following CollectionSpace layer:

• Services

Procedure

Application layer

Find your tenant folder in the Application layer

(Or instead see Finding your tenant folder.)

Find or create the relevant configuration file within your tenant folder

Edit that file to add your extension schema and its new fields

• Edit the relevant Application layer configuration file in your tenant folder you want to change (within tomcat-main/src/main/resources/tenants/{mymuseum}) in a text editor, to add XML markup for:
  • Your extension schema
  • Any fields you want to add inside that schema.

Add a tag for your extension schema

The markup to create an extension schema requires just a single XML tag, of the form:

By convention, the schema name should:

• Start by including the record type (matching the record type, whether plural or singular, specified in the common schema)
• Contain underscores as word separators

For instance, persons_naturalhistory would be a suitable name for an extension schema that adds fields to the Persons record for the natural history community of practice (domain), and acquisitions_mymuseum could be used to name an extension schema that adds fields to the Acquisition record that are specific (local) to the museum named mymuseum.

By convention, as well, the schema URL should be of the form:

For instance:

Add a tag for your new field in that extension schema

The markup to add a field depends on the type of field you're adding: plain text, date, number, and the like. Here's an example of a tag that adds a simple plain text field, within the two example extension schemas above:

The value of the section="" attribute for your field should match the value of the <services-record-path id="" attribute for your extension schema, in order to associate your field with your extension schema.

By adding this <field> tag below the <services-record-path> tag shown above, you will now have the following contents in your configuration file, for each of the two examples above:

Add wrapper tags to ensure your new extension schema and field(s) are merged into the correct place

You also need to add 'wrapper' tags within the relevant Application layer configuration file in your tenant folder, to ensure that the new extension schema you've added, as well as any fields you've added to that schema, are merged into the correct place within the corresponding default configuration file.

Often, this can be as simple as:

• Adding a top-level <record id=""> tag, at the top of that file. (That tag should be identical to the top-level tag in the default configuration file into which you'll be merging your changes.)
• Adding a corresponding </record> closing tag, at the bottom of that file.
• Adding a <section id=""> tag, above the field(s) you're adding. (That tag should be identical to one of the <section> tags in the default configuration file into which you'll be merging your changes, and preferably identical to a <section> tag that contains existing field(s) that are at least somewhat related to the ones you're adding.)
• Adding a corresponding </section> closing tag, below the tags for the field(s) you're adding.

By adding these <record id="">...</record> and <section id="">...</section> wrapper tags, you will now have the following contents in your configuration file, for each of the two examples above:

For two 'real world' examples of how new extension schemas, each containing one or more fields, were added to the Cataloging (aka CollectionObject) and Person records in CollectionSpace's sample Lifesci tenant, see Merging your changes into CollectionSpace's Application layer.

Each example of Application layer configuration files in the Lifesci tenant folder includes:

• The wrapper tags at the top and bottom of the document.
• The tag for the extension schema to be added
• The tag(s) for the field(s) to be added in that schema.

Find or add a reference to that configuration file in your tenant's main configuration file

Build the Application layer

(Or instead see Configuring CollectionSpace's Application Layer - An Overview.)

Services layer

Run a command to generate Services artifacts for your extension schema

User Interface (UI) layer

Find your tenant folder in the UI layer

(Or instead see Finding your tenant folder.)

Find or create the relevant HTML template file in your tenant folder

• If it isn't already present, make an html folder within your tenant folder.
• If it isn't already present, make a pages folder within that html folder.

• Afterwards, you will then have this folder structure. (Other folders may be present as well.)

• Within your tenant folder, check the /html/pages folder to identify whether the relevant file - the file in which you want to add fields - is already present.
  • If not, copy the relevant file from the defaults folder, src/main/webapp/defaults/html/pages, into the matching (corresponding) location within your tenant folder, src/main/webapp/tenants/{mymuseum}/html/pages, where {mymuseum} represents the short name of your museum.

Add the markup for your new field to that HTML template file

• Edit the relevant HTML file you want to change (within src/main/webapp/tenants/{mymuseum}/html/pages) in a text editor, to add the HTML markup for your new field.

The markup you will add will vary, depending on the type of field you're adding.

Find or create a message bundle file for your tenant

• Within your tenant folder, find the bundle/core-messages.properties-overlay file.
  • If this file and/or folder doesn't exist:
    • If needed, create a new folder within your tenant folder, named bundle
    • Create a new text file within the bundle folder, named core-messages.properties-overlay

• Afterwards, you will then have this folder/file structure within the UI layer source code folder, inside the src/main/webapp/tenants folder:

Add a text label for your new field to the message bundle file

• Edit the core-messages.properties-overlay file in a text editor.
• Create a text label for your newly added field.

Copy your changes to the CollectionSpace server

(Or instead see Configuring CollectionSpace's User Interface (UI) Layer - An Overview.)

Test

After following the procedure above, use a web browser for the following steps:

• First, clear your Web browser's caches.
• If you are not already logged into your museum (tenant) on your CollectionSpace system:
  • Visit your museum's (tenant's) login page. For details, see the Test section of Creating your new tenant.
  • Login as a user in your museum (tenant).
• Navigate to the page containing your new field.
• Look for that field on the page.
• Enter data in that field.
• Save the record.
• Verify that the data you entered is still displayed in that field.

If it doesn't work

If you don't find your label in the message bundle file:

• Open the HTML template file for the relevant page, and find the class="" selector for the relevant field in that template.
• Add a new line to the message bundle file, where the property value (to the left of the ":") on that line represents a modified version of its class selector in its HTML template, following the naming conventions described in The message bundle file in the UI layer.

If the label change doesn't appear, make sure that:

• You've reloaded the relevant page in your web browser to see your changes.
• You've edited the correct file.
• In that file, you've changed the label associated with the correct field. In addition to double-checking your editing, you can also open the HTML template file for the relevant page, and verify that the property value of the label you've changed closely matches the class="" selector for that field in that template.
• You've copied (deployed) the changes in your tenant folder to your CollectionSpace server.
• You've either restarted the cspace server or set up your server to automatically reflect changes.