Vocabulary Editor¶

The Vocabulary Editor lets you work with the Common Vocabulary to define the set of common and site-specific vocabulary terms that archivists will use when working with items in your collection. The Vocabulary Editor lets you define terms for these metadata fields:

• Type
• Subject
• Place

To define terms for other fields, use the Simple Vocab plugin.

Launch the Vocabulary Editor

To get to the Vocabulary Editor, click Vocabulary Editor in the left admin menu. You'll then see a page similar to the one shown below that lists the terms that are currently defined for your site.

Meaning of fonts and colors in the Vocabulary Editor

The Vocabulary Editor uses different effects to convey information about terms. In the previous screenshot above, all of the terms appear as blue, underlined text to indicate that they are common terms; however, you may see other effects as shown below.

This table explains the numbered effects shown above.

#	Appearance	Meaning
1	Red	Unmapped site term
2	Text inside blue button	A suggested common term (see Apply a suggested term)
3	Blue, no underline	Common term with no corresponding Nomenclature term
4	Blue, underlined	Common term corresponding to a Nomenclature term
5	Black	Mapped site term with common term in parentheses.

---

The sections that follow explain how to:

• Apply a suggested term
• See which items use a term
• Choose a common term
• Add a new vocabulary term
• Edit an existing vocabulary term
• Remove a vocabulary term
• Merge terms
• See all vocabulary terms
• See Nomenclature definitions

Apply a suggested term¶

Sometimes you'll see a blue button like the one below next to a red unmapped site term.

The blue button is a special feature that provides you with a suggestion. When you add or edit an unmapped site term, the Vocabulary Editor looks for a common term that has the same leaf as the unmapped site term. When there's a match, the blue button appears as a suggestion for you to use the matching common term.

In this example, the matching leaf is Cyanotype. If you like the suggestion, you can click the button, and then click Update on the confirmation dialog (shown below), to change the term to use the suggestion and to update any items that use the term.

The suggested term is usually appropriate, but not always, so be sure you want to use the term before you click the Update button. There is no undo, but if you update the term by mistake, you can always edit the term to change it back to what it was before.

See which items use a term¶

To see which items use a specific term, click the number that appears to the left of the term. The screenshot below shows that 35 items use the term Image, Art, Drawing. You can click on 35 to see search results for the 35 items that use that term as their Type.

A zero will appear if no items use that term. Unless you anticipate that archivists will need the term in the future, remove it from the vocabulary.

Choose a common term¶

The next two sections on adding and editing terms require that you choose a term from the Common Vocabulary. To choose a common term, follow these steps:

1 – Open the common term chooser dialog

To open the dialog, click the Choose Common Term button in the term's edit form (see next section).

2 – Start typing in the field at the top of the chooser dialog

As you type, terms that match what you enter will appear as suggestions as shown below.

3 – Click the term you want

In the example above, when you click on Object, Writing, Letter Opener, the chooser dialog will close and that term will appear in the Common Term field of the edit form.

Add a new vocabulary term¶

Follow these steps to add a new term:

1 – Choose the vocabulary kind

Select Type, Subject, or Place from the Vocabulary dropdown list at the top of the Vocabulary Editor page. The page will update to show the terms defined for your site for that kind.

2 – Click the Add button at the top of the page

In the screenshot above, the button says Add Subject because Subject is selected in the Vocabulary dropdown. It will say Add Type or Add Place when Type or Place are selected. Click the button to open an edit form as shown below.

3 – Fill in the form

Do one of the following:

• Enter a Site Term or
• Choose a Common Term or
• Enter a Site Term and choose a Common Term

4 – Click the Save button

When you click the Save button, the term will be added to your site's vocabulary and will appear in the corresponding field's dropdown list when you add or edit an item. For example, when you add a new subject term, the new term will appear in the Subject dropdown when you are adding or editing an item.

Edit a vocabulary term¶

Follow these steps to change an existing term:

1 – Open the edit form for the term

Click the pencil icon located to the far right of the term.

2 – Edit the term

Change the Site Term and/or choose a different Common Term.

In practice, you should never need to use the Erase Common Term button unless you wanted to convert a mapped site term to unmapped. Use of unmapped site terms is not recommended.

3 – Click the Update button

When you click the Update button and confirm that you want to make the update:

• The term will be changed in your site's vocabulary
• It will appear in the corresponding field's dropdown list when you add or edit an item
• Every item that uses that term will be updated with the change

Remove a vocabulary term¶

To remove an existing term, follow the steps above to edit an existing term, but then click the red Remove button in the lower right. The button will only appear if the term is not used by any items. To remove a term that is being used by one or more items, first edit each of those items to use a different term. When no item is using the term, you can remove it.

Merge terms¶

Occasionally you'll run into the situation where you have two similar terms that you would like to merge into one, but each term is being used by different items. Simply edit one term to match the other (or change both to the term you like), and the Vocabulary Editor will automatically merge the two terms into one and update all the items that use them to use the new term. After the merge you'll see that the usage count for the merged term is the sum of the usage counts for the original terms.

See all vocabulary terms¶

To see all the terms for a vocabulary, click the view hierarchy link located at upper right of the Vocabulary Editor page. The name of the link depends on which vocabulary you are editing. For example, if you are editing the Type vocabulary, the link will be View Type Hierarchy.

The screenshot below shows the first few dozen terms for the Type vocabulary. To get back to the Vocabulary Editor, click the Return to Vocabulary Editor link at upper right.

Searching the page

The Vocabulary Hierarchy page is very long. For Type and Subject terms, it contains thousands of terms. You can use your browser's search feature to find terms on that page. On most browsers, you can get a search box by pressing Ctrl-F on Windows, or Command-F on Mac.

Nomenclature definitions

Terms that have a blue hyperlink at the end are from Nomenclature 4.0. Click the link to see that term on the Nomenclature website. See the next section below for more information.

Public Page

You can share a public link to the Vocabulary Hierarchy page by editing the URL to remove remove admin. For example, if the URL is

https://swhplibrary.net/digitalarchive/admin/vocabulary/tree?kind=1

then the public URL is as shown below (click it to see what the public page looks like)

https://swhplibrary.net/digitalarchive/vocabulary/tree?kind=1

See Nomenclature definitions¶

In the Vocabulary Editor, terms that come from Nomenclature 4.0 appear in blue, underlined type as shown in the screenshot below.

Click on a blue, underlined term to see its definition on the nomenclature.info website. The screenshot below shows the nomenclature.info page for the Nomenclature term Annual Report.

The page above reveals that the Digital Archive common term for Document, Report, Annual Report is the same as Nomenclature term #13286 which has a six level hierarchy:

Category 08: Communication Objects
    Documentary Objects
        Administrative Records
            Report
                Administrative Report
                    Annual Report

This comparison is useful for someone who has experience working with Nomenclature and wants to understand how Digital Archive common terms map to Nomenclature terms.

Simple Vocab plugin¶

This section briefly addresses vocabularies that a site may be using in addition to the Type, Subject, and Place vocabularies provided by the Common Vocabulary feature.

The Omeka Simple Vocab plugin is a good and easy to use way to manage modest vocabularies that a site might use for site-specific terms such as status values or collection names. The Digital Archive uses Simple Vocab for the Rights field values.

You can add new terms to your vocabulary at any time, but if you rename a term, your vocabulary will become out of sync with items that use that term. Unlike the Vocabulary Editor which automatically updates items when you edit a term, Simple Vocab has no such feature. To avoid problems, follow this approach when renaming a term.

• Rather than rename a term, add a new term having the new name
• Edit every item to use the new term
• When no more items use the old term, remove it from the vocabulary

If you don't heed the advice above, and instead just rename the old term, when you go to edit an item that uses the old term, you won't see any value in the dropdown list. That's because the edit page will populate the dropdown list with the updated vocabulary terms and won't be able to match-up the item's old term with any term in the list and so it will just show Select Below.

If there are too many items using a term to edit each one, you can use the Bulk Editor, but first learn how to make bulk edits and be sure to reindex your Elasticsearch indexes afterward.

---