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
We need to link here to a readable overview of how schemas are handled in CollectionSpace. For now, the following brief overview will need to suffice.
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 a reference here to a new document that identifies how to add XML markup for various types of fields, including text fields, number fields, date fields, and more. In advance of that document, see the current document HTML field level templates, which includes some (slightly dated) examples of Application layer configuration for a small number of field types.
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="">
and ...</record>
<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 thathtml
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.
- If not, copy the relevant file from the defaults folder,
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.
Add a reference here to a new document that identifies how to add HTML markup for various types of fields, including text fields, number fields, date fields, and more. In advance of that document, see the current document HTML field level templates, which includes some (slightly dated) examples of HTML markup for a small number of field types.
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, namedcore-messages.properties-overlay
- If needed, create a new folder within your tenant folder, named
- If this file and/or folder doesn't exist:
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.
See The message bundle file in the UI layer for detailed instructions on how to find and edit the relevant text labels.
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
Expand as needed on the following bullet points, which are currently just telegraphic reminders:
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 itsclass
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.