Week 4. Advanced Building and Basic Computational Methods

Topics: Customization; Computational Methods; CollectionBuilder

Today, we will further customize our exhibits. In doing so, we will gain a better understanding of how Jekyll reads our CollectionBuilder templates.

Learning Objectives

  • Understand how Jekyll generates your site.
  • Understand how Jekyll uses the Liquid programming language.
  • Create new pages using markdown, YAML, and liquid.
  • Be able to use liquid includes to further customize your pages.
  • Be able to customize your collection’s pages using the different config files.

More About Jekyll and Site Generation

Our short lecture explains some of the key aspects of navigating Jekyll and the CollectionBuilder framework in more detail. We’ll cover:

  • _config.yml: the file you used to structure your site.
  • Key-value pairs: Linked data items that establish constants (the key) and variables (the value). Collection Builder explains key-value pairs in their glossary entry about YAML
  • YAML front matter: A small block of code that tells Jekyll more about how you want your page to look.
  • Liquid: the programming language used by Jekyll.

Customizing Your CollectionBuilder Exhibit

We will address some of the key areas of CollectionBuilder site customization today. Our work today is in no way exhaustive. CollectionBuilder’s documentation explains even more ways you can further customize your site. The CB team is often exploring new ways to tweak the framework and sharing those developments via their documentation, discussion forum, and slack channels.

Edit Your About Page: Content and Exploring Liquid Includes

  1. Navigate to the pages folder.
  2. Open about.md.
  3. Generate your site using the terminal. A quick reminder:
    • In the terminal, type the command bundle exec jekyll s and press enter. This “jekyll serve” command will generate the site for you on a local server on your computer.
    • In the terminal you’ll see some text appear, including a URL that appears after the title “Server address:”
    • Hold down Ctrl and click this link to open the site in your browser (or copy the URL and paste into a private window).
  4. Notice how the html generated by Jekyll includes a lot more content than the code in your markdown. This is because Jekyll is reading the markdown written in the About page and following the nesting of Liquid includes to pull from multiple places in your repository to generate this page.
    • If you scroll to line 27 of about.md, you will see an include with the following path: cb/about_the_about.md.
    • Navigate to cb/about_the_about.md by going to the _includes folder in your repository and then the cb folder. There you will find about_the_about.md and a lot more markdown that resembles the html in your browser.
    • Now scroll down the About page in your browser to see some includes that you may want to use in your exhibit.
  5. Let’s remove some of the CB instructional content and add our own so visitors can learn more about our exhibit.
    • Remove the two includes above ## About the Collection.
    • Remove all the content below the ## About the Collection header.
  6. Add markdown below ## About the Collection to say something about your site. Some potential textual content includes:
    • Why your collection is interesting.
    • Where the original contents are located.
    • Future expansions of your exhibit and its relationship to the collection
    • Who you and your team are.
  7. Add an image using an the image.html include:
    • Identify an image you want to highlight on this page and record the objectid.
    • Copy the include code block: {% include feature/image.html objectid=yourid width="50" %} and paste it above the ## About the Collection header.
    • edit the objectid key by changing the value to the right of the = sign. This should be an objectid from your metadata, such as latam001. (Tip: Remember what we discussed earlier about key-value pairs)
    • You can also change how much space the image takes up on your page by editing the value of the width key.
  8. Add a card using the card.html include:
    • Identify an image that will work well in a card and record the objectid.
    • Copy the include code block: {% include feature/card.html header="This is a Card" text="The card features an image from the collection as a cap" objectid="demo_001" width="25" centered=true %} and paste it in between paragraphs in your About the Collection section.
    • Edit the following key-value pairs within the code block:
      • header
      • text
      • objectid
    • We will keep the default values for the width and centered keys, but you can change these to alter the location and appearance of the card.
  9. Save your about.md file and refresh your browser to see how the page changed. If there is something appears incorrect or you don’t like how it looks, edit further.
  10. When you are happy with the current iteration of your About page, you can save, stage, commit, and push changes.

Create a New Page: Markdown and Your Directory Hierarchy

  1. Navigate to the pages directory.
  2. Create a new file:
    • Click the add new file icon in your VS Code explorer.
    • Name the file and include the .md extension. Let’s name our file history.md.
  3. Add the necessary YAML front matter variables so Jekyll knows how to build our page:
    • You can do this manually by adding the title, layout, and permalink key-value pairs or copy the following code block: 
        ---
  title: Collection History
  layout: about
  permalink: /history.html
  ---
    • Add content below the front matter that explains where your collection came from.
  4. Add your page to the config.nav.csv file. This adds your new page to the navigation bar so it is more easily discoverable.
    • Navigate to the _data directory and open the config-nav.csv file.
    • Create a new row in the csv by adding values that correspond with display_text and stub keys.
    • These values will correspond to your YAML front matter and your row will look like this: Collection History,/history.html
    • Be sure to include the comma between the two values! Remember that the commas in a CSV represent a column divider.
  5. Save, stage, commit, and push changes.

Customize Display Options: Using the theme.yml File

  1. Navigate to the _data folder and open the theme.yml file.
  2. Scroll through and read the commented text to see what this file controls.
    • You can use this file to alter every page the site builds.
    • Some page structures may not need alteration at this time, but it is still a good idea to familiarize yourself with what you can change and how you may want to do so. To review how to change settings that we do not cover today, visit CB’s Theme Configuration Options documentation.
  3. We will edit our feature image and change the map view for anyone using geographic data.

Customizing the Feature Image

The feature image will be the banner image for your home page.

  1. Locate the # HOME PAGE header in the theme.yml file.
  2. Locate an image from your collection that is striking or representative of the collection. It is also a good idea to use an image that views well in a landscape setting. Record the objectid.
  3. Find the featured-image key and change the image value to the objectid of your preferred image, such at latam001. (You can also use relative locations or a URL)
  4. Save this change and refresh your browser to review its appearance.
    • If you are unhappy with how CB is displaying a portion of the image, you can change the padding and the positioning:
      • home-title-y-padding key can be used to show more or less of the image. Use the range of 2em to 20em to adjust.
      • home-banner-image-position key can be used to determine which portion of the image will be displayed. You can use the values top, center, or bottom.

Customizing the Map Page

The theme.yml file has default map page settings that center around Idaho, the location of the creators of CollectionBuilder. If you have added geographic data (latitude and longitude coordinates) to your metadata, you will want to adjust the map settings so that your objects are viewable when a visitor lands on your map page.

  1. Scroll down to the # MAP PAGE header in the theme.yml file.
  2. Find latitude and longitude coordinates that are roughly in the center of where your objects are located.
    • For example, if your objects are located across South America, you may want to pick a point in southwest Brazil to better display your objects on the map page.
    • Quick tip: To find map coordinates quickly, go to Google Maps and click your desired point. Then, right click your selected point on the map and a popup box will appear with your point coordinates and other options. Click the point coordinates to copy them to a clipboard.
  3. Change the values of the latitude and longitude keys by using the coordinates you copied from Google Maps.
    • Be sure to correctly separate latitude and longitude.
    • Be sure to include the - sign if it is in your coordinates.
  4. Change the zoom-level key to a value that allows the map to display all your objects when a visitor first lands on your map page.
    • zoom-level can be set at any whole number between [0 - 18]
  5. Save, stage, commit, and push changes.

More Configuration: Using the Many config.csv Files

Many of the CollectionBuilder pages are configured using “config” CSV files. You can find these in the _data folder. The different CSVs with the config- prefix will help you further customize your site. For example, you can use the config-map.csv file to change which information from your metadata appears in the pop-ups that appear on your map. Today, we are going to customize our navigation and the browser page using the config CSVs.

Changing the Configuration of the Navigation Bar

We are going to create a dropdown menu to demonstrate how you can configure the navigation bar.

  1. Navigate to the _data folder and open the config-nav.csv file.
  2. Note the three different columns of the csv: display_name, stub, dropdown_parent.
    • We will alter and add values to create a dropdown menu.
  3. Create an “Explore” dropdown by adding a new row below Home. The row should read as follows: Explore,.
    • The comma is necessary to signal the end of the display_name value.
  4. Add the following rows to the Explore dropdown: Browse, Subjects, Locations, Map, Timeline.
    • To do this add a ' (comma) after the stub value in each row and then add Explore
    • Do not use spaces!
  5. Save the CSV and refresh your browser to see if the navigation updated.

Changing the Configuration of the Browse Page

Customizing your browse page allows you to better curate how your visitors explore your collection items. CB uses default metadata categories in their browse page that may not correspond with the metadata you included in your spreadsheet. The browse page displays specific metadata as a card for each object in your collection. This exercise will teach you how to change the display on each card and alter how one sorts the page.

  1. Navigate to the _data folder and open the config-browse.csv file.
  2. Note the different columns and review CB’s config-browse documentation to learn more about the categories.
  3. Review your metadata csv and identify a category you would like to add to an object card.
  4. Create a new row and add the field name. For example, if you want to include the object description, use the field name description. Then add a , to complete the value.
  5. Add a display_name value. This will help the viewer understand what they are reading. If you are following our example, add Description,.
  6. Next, add another way for users to sort your items.
  7. Add a sort by location by changing the location row as follows: location,,true,,Location
    • The commas are required so that your sort by location value is in the correct column.
    • This will create a new sort by drop down to the right of the search bar on the Browse page.
  8. Save your file and refresh your browser to make sure your new sort option displays correctly.
  9. Correct as needed, then save, stage, commit, and push changes.
Week 3. CollectionBuilder and Local Development Resources