Documentation

Customize

Refer to the Theme File section for more information about customizing the various pages in your collection. The files discussed in this section will help you customize the website to fit the metadata that’s driving it.

Each of these “config-“ files is a CSV (comma-separated-values) file that is stored in the /_data/ directory of your repository. We recommend that you edit them using your text editor, but Google Sheets or another spreadsheet program (that supports UTF-8 encoding) will also work.

This CSV controls what and in what order the links appear in your collection’s navigation bar.

  • display_name: This field determines what words will display in the nav bar.
  • stub: This field determines what link the display text will follow.
  • dropdown_parent: This field is used to add dropdown functionality to your nav bar. Use it to indicate items that should appear inside a dropdown menu. It should be left empty for any non-dropdown nav item. Follow these rules to configure your nav dropdown:
    • If the item has a stub, but no value in dropdown_parent, it becomes a normal nav item
    • If the item has no stub, it will become a dropdown menu
    • If the item has a value in dropdown_parent, it will only show up under its parent dropdown

Example

display_text,stub,dropdown_parent
Home,/,
Browse,/browse.html,
Subjects,/subjects.html,
Map,/map.html,
Timeline,/timeline.html,
Data,/data/,
About,,
About the Collection,/about.html,About
CollectionBuilder,/tech.html,About

Some Explaining

The above CSV will create 7 links in the nav bar for the referenced pages. These same nav items will also automatically appear in the footer.

You might have noticed that the Locations Page has been deleted, so it won’t show up in your nav bar. If you want to add it back in, you’ll just need to add a line after the Subjects,/subjects.html, line that reads: Locations,/locations.html,

How the Dropdown Works

The last two lines of this CSV will appear within the “About” dropdown menu. To enable this, “About” must have no value in stub or dropdown_parent cells–this will direct the code to make “About” a dropdown button and store any link that lists “About” as it’s dropdown_parent in its dropdown menu. So in the above, when About is clicked the dropdown menu will appear with “About the Collection” and “CollectionBuilder” listed, both linking to their respective pages.

Note: Dropdowns do NOT appear in the footer nav. The parent will appear, with a link to the top child.

Metadata / Item Page Configuration (config-metadata.csv)

The most important CSV (if you’re measuring by the number of pages it creates!) is the one that controls the metadata. The config-metadata.csv controls how an item’s metadata is displayed on its web page, as well as configuring the machine-readable meta markup in the underlying code. The columns are described below:

  • field: This variable corresponds to the field listed in the metadata for the collection. For instance, if you have a metadata field called “original-collection”, you would put original-collection here.
  • display_name: This variable is how you’d like the field to be described on the item page. So, using the example above, if you’d like the field “original-collection” to appear as “Original Archival Collection” on the item page, you’d enter “Original Archival Collection” in the second column.
  • browse_link:
    • Options: true or leave blank.
    • This option controls if the element will be represented as a link from the item page back to the Browse page. It is most useful for those fields, like “subject”, that often contain multiple values (separated by a semicolon). So, for instance, if you wanted to make the subjects in your “subject” field separate out into individual links, you’d enter true in the third column of the config-metadata.csv

The options below this point are used by CDM and SA only, and are not necessary to make the collection itself work and will not affect the display. However, configuring these options adds rich machine readable markup to each item page, making your objects more discoverable by search engines.

  • dc_map:
    • Options: the prefix DCTERMS plus a property name from the DC Terms namespace, written like: DCTERMS.term_from_terms_namespace
    • This option allows you to map your metadata field to a Dublin Core property to be added in machine readable meta markup. So, continuing with our example, if you’d like to map the “original-collection” field to be read as a Dublin Core Source, you’d enter DCTERMS.source in the third column.
    • Recommended fields to map include:
      • DCTERMS.title
      • DCTERMS.creator
      • DCTERMS.created
      • DCTERMS.description
      • DCTERMS.subject
      • DCTERMS.type
      • DCTERMS.rights
  • schema_map:
    • Options: any property name from Schema CreativeWork type. Copy the exact property name, as this value will be turned into schema JSON-LD markup.
    • Schema is a standard designed to provide structured semantic markup for search engines to better understand content of web pages. This option allows you to add Schema markup in JSON-LD format to item pages driven by the object metadata.
    • Recommended fields to map include:
      • headline (i.e. the title)
      • creator
      • dateCreated
      • description
      • keywords
      • contentLocation
      • encodingFormat (This corresponds to the format field of CollectionBuilder items)
      • license (Should only be used with a standardized rights URL)

Example

field,display_name,browse_link,dc_map,schema_map
title,Title,,DCTERMS.title,headline
creator,Creator,,DCTERMS.creator,creator
date,Date Created,,DCTERMS.created,dateCreated
date-is-approximate,Approximated Date
description,Description,,DCTERMS.description,description
subject,Subjects,true,DCTERMS.subject,keywords
location,Location,true,,contentLocation
identifier,Source Identifier
type,Type,,DCTERMS.type
format,Format,,,encodingFormat
rightsstatement,,,DCTERMS.rights,license

Browse Links

In the case of this example, only the location and subject fields have a value (true) for “browse-link”, so those fields will turn each individual subject and location term (delimited by semicolon in that field) into a link (e.g. browse.html#dogs) that links back to a browse page view that will only list those items that share that term.

Dublin Core and Schema Markup

The title, creator, date, description, subject, and type fields in the above example all have a dc_map variable, so each of them would be represented in the item page’s <head> meta section in a way that follows the Dublin Core schema to enable better machine readability and indexing.

Similarly, the title, creator, date, description, subject, location, format, and rightstatement fields all have a schema_map entry, so each of these would be represented in an item page’s <head> meta section in a way that follows Schema.org recommendations in order to enable better machine readability and indexing.

Browse Page Configuration (config-browse.csv)

The Browse page displays each item in the collection as a “card,” which is a design feature common to Bootstrap. At the top of the page, a search box allows users to limit the display by searching for certain terms. We also use subject links throughout the site that link back into the browse page and filter the collection based on the filter chosen.

So, for instance, if on the Subjects page, you clicked a button for “Forests,” you would actually be clicking a link whose url ended as “browse.html#forests.” The Browse page would take anything after the hashtag (‘#’) and filter the collection’s cards by it.

The Browse page configuration CSV allows you to control which metadata appears on a card for each item. Title appears on the card automatically. After that, you can add whatever metadata you’d like to the csv, as well as determine how that metadata will be displayed.

  • field: Selects the field from your metadata CSV.
  • display_name: Determines the field name as it is displayed to users.
  • btn: Determines whether the field displays as a button.
    • Options: true or leave blank
    • true will turn all metadata in that field into buttons, and is recommend for fields that have multiple entries, like ‘subject.’
  • hidden: Determines whether this field is hidden.
    • Useful when you don’t want a metadata field to be visibly present on Browse page cards, but still want to filter for that field.

Example

field,display_name,btn,hidden
date,Date,
description,,
subject,,true
location,,true

If you want to add a description to the browse cards, and label it “Description” on the user interface, you would include a value of description in the “field” column and then include Description as the value of that row’s “displayName” column.

If you want to include items’ descriptions on the browse cards but feel that including the label is unnecessary, you could simply include a value of description in the “field” column and then leave that row’s “displayName” column blank. The above example embodies this approach.

Map Page Configuration (config-map.csv)

The config-map.csv determines what information displays on the pop-ups on the map. More on map search options can be found on the theme page

  • field: Determines the metadata field that is included on the pop-up.
  • display_name: Determines the label that is displayed for that field.
  • search: Determines whether the field is searchable.
    • Options: true or leave blank

Example

field,display_name,search
date,Date,true
creator,Creator,true
location,Location,true

Table Configuration (config-table.csv)

The table appears on the “Data” page. It uses DataTables to generate a table that can be searched, sorted, and downloaded as a whole or in a filtered version.

We recommend not using more than 5 or 6 fields here, as the table can become overcrowded.

  • field: Determines the metadata field that is included on the table.
  • display_name: Determines the label that is displayed for that field.

Example

field,display_name
title,Title
date,Date
creator,Photographer
subject,Subjects

Theme Color Configuration (config-theme-colors.csv)

For simplicity, CollectionBuilder uses pre-compiled Bootstrap CSS. However, to make basic theming possible, we have added some code in _sass/_theme-colors.scss based on Bootstrap Sass to generate custom color CCS for btn-, btn-outline-, text-, and bg- classes. The custom classes can override existing Bootstrap theme colors or create new color classes.

By default, these options are not used.

To add custom colors, edit the two columns in the _data/config-theme-colors.csv:

  • color_class: The name you’ll use to designate the color (i.e. the part after the - in btn-primary).
    • example –> primary
  • color: Add the color in hex code.
    • example –> #4232a8

Any “color_class” with a “color” value will generate a btn-, btn-outline-, text-, and bg- class for the color, e.g. btn-primary, btn-outline-primary, text-primary, and bg-primary. Any “color_class” with a blank “color” will be ignored. For convenience, the standard Bootstrap theme colors are provided to fill in if desired, which will override the existing Bootstrap colors. Adding a non-Bootstrap “color_class” will generate new custom btn colors. E.g. “color_class” special will generate CSS for .btn-special and .btn-outline-special.

CollectionBuilder uses btn-primary, btn-outline-primary, btn-success, btn-info, btn-outline-info, btn-outline-secondary, btn-light, and btn-outline-light in page layouts, so overriding those styles will have immediate effects on the colors. The nav elements use bg-dark and text-dark by default.

Search Configuration (config-search.csv)

This CSV enables GH users to select which metadata fields they would like indexed for the collection object search powered by Lunr.js. The values here will determine the results that appear when the site’s users search for a term or phrase using the search box on the right-hand side of the header. Three columns in this CSV allow you to configure your search:

  • field: Determines the metadata field to be indexed for search
    • Example: title, date, description, etc.
  • index: Determines whether the field is searchable.
    • Options: true, false
  • display: Determines whether the value of that metadata field is displayed in the search results.
    • Options: true, false
« Theme File Back to Top Finish »