Making changes to YMLs and Configs
YMLs
Nomenclature and anatomy of YML files
This is an excellent article on YML files: https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started
YML files are made up of arrays and key-value pairs,. In the following example,en: and brand: are arrays, and each line within an array is a key: value pair where the key appears on the left of the colon and the value appears on the right.
en:
brand:
title: ArchivesSpace Public Interface
title\_link\_text: Return to the ArchivesSpace homepage
welcome\_head: Welcome to ArchivesSpace
welcome\_message: |
<p>Search across our collections, digital materials, and more.</p>
welcome\_page\_title: ArchivesSpace Public Interface
The array and key are referenced by the ArchivesSpace core code. Do not ever change the name of an array or a key; the only thing you should edit is the value.
Be sure the keys exist in the version you're working with
We and our customers have been modifying these files over time. If you are working with a file that has already been modified, remember to check that the arrays and keys you're working with still exist in the version you're on. You do this by comparing what you're working with to the defaults for the version you are aiming for.
Compare the following defaults:
2.8.1
en:
brand:
title: ArchivesSpace Public Interface
title\_link\_text: Return to the ArchivesSpace homepage
home: Home
welcome\_head: Welcome to ArchivesSpace
welcome\_message: |
<p>Search across our collections, digital materials, and more.</p>
welcome\_search\_label: "Find what you're looking for:"
welcome\_page\_title: ArchivesSpace Public Interface
3.4.1
en:
brand:
title: ArchivesSpace Public Interface
title\_link\_text: Return to the ArchivesSpace homepage
welcome\_head: Welcome to ArchivesSpace
welcome\_message: |
<p>Search across our collections, digital materials, and more.</p>
welcome\_page\_title: ArchivesSpace Public Interface
The keys home: and welcome_search_label: were removed or moved out from under this array between versions 2.8.1 and 3.4.1. Any values in these deprecated keys will at best do nothing and at worst cause an error; any deprecated keys and their values must either be removed or moved according to the version you're aiming for.
Removing keys
Deleting arrays or keys from YMLs does not remove them from the application. If ArchivesSpace goes searching for something in a YML and doesn't find it, it simply reverts to the default instead of removing the element. If you wish to remove an element, try setting it to an empty string. Note title: and title_link_text: below:
en:
brand:
title: ""
title\_link\_text: ""
welcome\_head: Welcome to ArchivesSpace
Truly suppressing a display element would have to be done with a plugin.
Adding keys
Adding keys that do not already exist in the default files has no affect on ArchivesSpace unless the addition of the key is supported by actual code changes (like a plugin). The ArchivesSpace core code can be thought of as asking questions of the various files listed here, like what should I call Resources? What is this configuration? Adding a key to a YML file without a complementary change in code is like providing an answer to a question that will never be asked.
If you are developing a plugin that truly does override default ArchivesSpace behavior, then the translations (YMLs) for those changes should be wrapped within that plugin and not stored in custom_locales.
Should custom_locales only support default behaviors by policy?