Adding Fields/Groups/Repeats/Controlled List

A Group is a set of Fields
A Repeat can either be a single field that Repeats or a Group that repeats
- these are considered functionally different by the UI and the service Layers and hence forth shall be known as:
  - RepeatField
  - RepeatGroup
A Controlled List is a field that has a set of predefined options. This is not something that the service layer currently cares about but the UI does
An authority term is a field that is associated with a known authority list. The services do care about this as they need to know what fields are authorities so the data appears in the RH side options in the UI. Therefore you can not make a term an authority without also making changes in the service layer

Cspace-config

All changes are made to cspace-config
for information about what and where to find cspace-config: Finding cspace-config
You can hot swap changes to cspace-config: How to activate changes to cspace-config

for changes to HTML templates see HTML field level templates

Add a field

open cspace-config
- if necessary follow the includes link to find the specific file you wish to edit
select the record you wish to add the field to e.g. <record id="collection-object" ... >
- it doesn't matter where you put the field in the record section, however, it is in your best interest to keep a consistent structure in the xml and therefore cluster fields together. The current structure is:
  - service url tags e.g. services-url
  - structure info
  - UI tags e.g. web-url, tab-url, row-selector, list-key
  - merge fields
  - rest of field/repeat/group tags
    - these tags are usually organised in an order similar to the presentation in the UI so it is easy to find the tags

the least information needed to add a field is:

<field id="newfieldname"></field>

this assumes that the UI selector for the field follows the pattern '.csc-{recordid}-{fieldid}' and the service id matches the field id. For complete list of field options see fields

Add a field with a controlled list

open cspace-config
- if necessary follow the includes link to find the specific procedure file you wish to edit

select the record you wish to add the field to

There are 2 types of controlled Lists:

Vocabularized controlled lists
Option controlled lists

option controlled list

This is the simplest type of controlled list field as the values of the controlled list are fixed and can not be changed at runtime. This should be used for short lists of immutable information

<field id="titleType">
	<options>
		<option id="">Please select a value</option>
		<option id="assigned-by-artist">Assigned by Artist</option>
		<option id="collection">Collection</option>
		<option id="generic">Generic</option>
		<option id="popular">Popular</option>
		<option id="series">Series</option>
		<option id="trade">Trade</option>
	</options>
</field>

vocabularized controlled list

These lists are dynamically created from an vocab-authority list. It is a semi authority as these terms wont be shown in the RH side of the UI. as they are not authorities in the truest sense but are actually a list of data which is variable and could be added to at runtime. It is assumed that the scope of these vocab-authorities is per-tenant and they are purely internal entities.

To use a vocabularized list there are 2 stages:

stage 1: Define the vocab-authority

in record type 'vocab' you need to add a new instance e.g
```
<instance id="vocab-lostatus">
	<web-url>loanoutstatus</web-url>
	<title-ref>loanoutstatus</title-ref>
	<title>loanedObjectStatus</title>
	<options>
		<option>Requested</option>
		<option>Authorized</option>
		<option id="agreement">Agreed</option>
		<option>Conservation</option>
		<option>Sent</option>
	</options>
</instance>
```
options are optional and only exist so that the vocabularized list can be preseeded if needed otherwise they will look in the service layer for a vocabulary with the title-ref. You can see a list of existing vocabularies at
http://nightly.collectionspace.org:8180/cspace-services/vocabularies/

Once the cspace-config has been changed and the either the webapp has been relaunched or the init url has been run to make it aware of the changes How to activate changes to cspace-config

Task	Url	Notes
Preseed all Vocabularies with the values in cspace-config	{collectionspace url}/collectionspace/tenant/{tenantname}/authorities/vocab/refresh	This will delete everything from the vocabularies and add in only the data in cspace-config
Preseed a specific Vocabulary	{collectionspace url}/collectionspace/tenant/{tenantname}/vocabularies/{web-url}/refresh
Reinitialize all vocabulary	{collectionspace url}/collectionspace/tenant/{tenantname}/authorities/vocab/initialize	This will just add in the options in cspace-config and wont remove anything that is no longer needed
Reinitialize a specific vocabulary	{collectionspace url}/collectionspace/tenant/{tenantname}/vocabularies/{web-url}/initialize

stage 2: Associate the list with a field

minimum information

<field id="loanedObjectStatus" autocomplete="vocab-lostatus" ui-type="enum"></field>

standard information

<field id="inscriptionContentLanguage" autocomplete="vocab-languages" ui-type="enum">
	<enum>
		<default>urn:cspace:core.collectionspace.org:vocabularies:name(languages):item:name(eng)'English'</default>
		<blank-value>Please select a value</blank-value>
	</enum>
</field>

the value of the autocomplete field can be multiple authorities/vocabularies but the string reference is the instance id from cspace-config file for that authority/vocabulary

Add an authority field

open cspace-config.xml
select the record you wish to add the field to

minimum information

<field id="borrowersContact" autocomplete="person-person"></field>

the value of the autocomplete field can be multiple authorities/vocabularies but the string reference is the instance id from cspace-config file for that authority/vocabulary

This presupposes that the authority you wish to associate to preexists. Generally Authorities are preloaded when the system is set up and if you wish to create a new authority then you need to see that documentation

Add a RepeatSingle

the simplest repeat is the single repeat.
At a most basic level you just surround the field with a repeat tag, making sure that you id's match the service layer element names

<repeat id="briefDescriptions" has-primary="yes">
	<field id="briefDescription"></field>
</repeat>

this maps to the services
fisheye collectionobj

<xs:element name="briefDescriptions" type="briefDescriptionList"/>
...

<xs:complexType name="briefDescriptionList">
	<xs:sequence>
		<xs:element name="briefDescription" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
	</xs:sequence>
</xs:complexType>

Add a RepeatGroup

(more information can be found at Adding a repeatable group
once again the basic answer is just surround the group of fields with a repeat tag, but Repeatable groups are slightly different as the services has more nesting than the UI wants therefore we use the complex id to help simplify this
so objectNameList/objectNameGroup represents the 2 elements that the services has but when the uispec is created for the UI only the second name objectNameGroup is used in the UI

<repeat id="objectNameList/objectNameGroup">
	<field id="objectNameCurrency" seperate_ui_container="true">
		<selector>.csc-object-identification-object-currency</selector>
		<options>
			<option id="">Please select a value</option>
			<option id="current">Current</option>
			<option id="archaic">Archaic</option>
		</options>
	</field>
	<field id="objectNameLevel" seperate_ui_container="true">
	<selector>.csc-object-identification-object-level</selector>
		<options>
			<option id="group">Group</option>
			<option id="subgroup">Subgroup</option>
		</options>
	</field>
	<field id="objectNameSystem" seperate_ui_container="true">
		<selector>.csc-object-identification-object-system</selector>
		<options>
			<option id="">Please select a value</option>
			<option id="art-and-architecture-thesaurus">Art &amp; Architecture Thesaurus</option>
			<option id="nomenclature">Nomenclature</option>
		</options>
	</field>
	<field id="objectNameType" seperate_ui_container="true">
		<selector>.csc-object-identification-object-type</selector>
		<options>
			<option id="">Please select a value</option>
			<option id="classified">Classified</option>
			<option id="denomination">Denomination</option>
			<option id="simple">Simple</option>
			<option id="taxonomic">Taxonomic</option>
			<option id="typological">Typological</option>
		</options>
	</field>
	<field id="objectNameLanguage" autocomplete="vocab-languages" ui-type="enum">
		<enum>
			<default>eng</default>
			<blank-value>Please select a value</blank-value>
		</enum>
	</field>
	<field id="objectNameNote"></field>
	<field id="objectName" mini="search"></field>
</repeat>

matches services

    <xs:element name="objectNameList" type="ns:objectNameList"/>
...

    <xs:complexType name="objectNameList">
        <xs:sequence>
            <xs:element name="objectNameGroup" type="objectNameGroup" minOccurs="0"
                maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="objectNameGroup">
        <xs:sequence>
                <xs:element name="objectName" type="xs:string"/>
                <xs:element name="objectNameCurrency" type="xs:string"/>
                <xs:element name="objectNameLevel" type="xs:string"/>
                <xs:element name="objectNameNote" type="xs:string"/>
                <xs:element name="objectNameSystem" type="xs:string"/>
                <xs:element name="objectNameType" type="xs:string"/>
                <xs:element name="objectNameLanguage" type="xs:string"/>
        </xs:sequence>
    </xs:complexType>

becomes to the UI

".csc-collection-object-objectNameGroup": {
    "decorators": [{
        "func": "cspace.makeRepeatable",
        "type": "fluid",
        "options": {
            "elPath": "fields.objectNameGroup",
            "protoTree": {
                ".csc-object-identification-object-type": {
                    "optionnames": ["Classified", "Denomination", "Simple", "Taxonomic", "Typological"],
                    "optionlist": ["classified", "denomination", "simple", "taxonomic", "typological"],
                    "selection": "${fields.objectNameGroup.0.objectNameType}"
                },
                ".csc-object-identification-object-language": {
                    "default": "14",
                    "optionnames": ["Please select an item", "German", "Chinese", "Middle English", "Italian", "Latin", "French", "Hebrew", "Portuguese", "Korean", "Japanese", "Ancient Greek", "Russian", "Spanish", "English", "Old English", "Arabic", "Swahili"],
                    "optionlist": ["", "german", "chinese", "middleenglish", "italian", "latin", "french", "hebrew", "portuguese", "korean", "japanese", "ancientgreek", "russian", "spn", "eng", "oldenglish", "arabic", "swahili"],
                    "selection": "${fields.objectNameGroup.0.objectNameLanguage}"
                },
                ".csc-object-identification-object-level": {
                    "optionnames": ["Group", "Subgroup"],
                    "optionlist": ["group", "subgroup"],
                    "selection": "${fields.objectNameGroup.0.objectNameLevel}"
                },
                ".csc-object-identification-object-system": {
                    "optionnames": ["Art & Architecture Thesaurus", "Nomenclature"],
                    "optionlist": ["art-and-architecture-thesaurus", "nomenclature"],
                    "selection": "${fields.objectNameGroup.0.objectNameSystem}"
                },
                ".csc-object-identification-object-note": "${fields.objectNameGroup.0.objectNameNote}",
                ".csc-object-identification-object-currency": {
                    "optionnames": ["Current", "Archaic"],
                    "optionlist": ["current", "archaic"],
                    "selection": "${fields.objectNameGroup.0.objectNameCurrency}"
                },
                ".csc-object-identification-object-name": "${fields.objectNameGroup.0.objectName}"
            }
        }
    }]
}

Add a Group

A group is technically a non repeating repeat and therefore is created in the same way but instead of surrounding with a repeat tag we surround with a group tag e.g.

<group id="role">
	<field id="roleId"></field>
	<field id="roleName"></field>
</group>

The service implementation is currently only in Roles and Permissions which is non-standard therefore this functionality might change
There is no current UI implementation of the group functionality

CollectionSpace Current Documentation

cspace-config Add Field, Group, Repeat