Specifying Options for Custom Page Data

At its root, custom data is a string of characters. For example: triptych or twitter or sun are all strings.

But, what if you want to present your users a specific choice? For example, instead of a text field where they could enter any word in the dictionary, imagine if you could present them an interface with radio buttons, checkboxes or a select field? What if you could attach a description to the Custom Data field?

In CleanSlate, we have the ability to specify options for our Custom Data. Take the following example:

Let's say we want to have the question, "Is it sunny outside today?" as custom data. Traditionally, here's how that would work in a template:

---
layout: default
custom_data_attributes:
  - is_it_sunny_outside_today
---

In Page Properties, that would look like this:

As you can see, this is not an ideal user interface to answer this question. Users could put any number of things into this field.

What if we could add options to this Custom Data Attribute to help simplify the responses we get? We can!

For this example, we're going to assume the answer to this question is either "Yes" or "No". Here's how that would look:

---
layout: default
custom_data_attributes:
  - is_it_sunny_outside_today:
    type: radio
    title: "Is it sunny outside today?"
    description: "Look out the window. Do you see the sun?"
    options:
      - "Yes"
      - "No"
    default:
      - "Yes"
---

Now that we've added a few extra options to our Custom Data, here's what the interface looks like in Page Properties > Custom Data:

As you can see, this is a vast improvement in our user interface. We limit the options editors have when inputting Custom Data while simplifying the process.

What types of fields are available for custom data?

The following type's are available:

• checkbox
• number
• radio
• select
• string
• text
• url

If you don't specify a type, it will default to string. This means CleanSlate will display an <input> without any restrictions for what is entered into it.

View each field types' documentation on Mozilla Developer Network using the links above to see a full listing of potential options and their definitions.

Options available to every field type:

• description
• title
• type

Examples of how you might use Custom Data:

Here are a few ideas:

• To show or hide a section of a page on your site.
  • Imagine you are redesigning a site and, over time, the content authors want to "enable" features on a per-page basis. You could use an <r:if> statement and have Custom Data with a Yes or No radio choice to show or hide this feature. The code might look like this:

<r:if v1="{$show_awesome_feature}" v2="true" op="=" type="boolean">
  <p>If you click "Yes" in Page Properties > Custom Data, this content will show up.</p>
</r:if>

Then, your template's frontmatter would look like this:

---
layout: default
custom_data_attributes:
  - show_awesome_feature:
    type: radio
    title: "Show the awesome feature?"
    options:
      - "Yes"
      - "No"
    default:
      - "No"
---

See the DIY Outdoors theme for a working implementation of this pattern.

• Maybe you need to capture a specific string, but don't want to force users to enter the exact string.
  • For example, imagine you want to capture wvu-triptych, wvu-diptych or wvu-media-object. It'd be a tough sell to get a content author to remember those; however, with Custom Data, we can throw those strings into a select box so it's easy for them to choose one.

---
layout: default
custom_data_attributes:
  - pattern_name:
    type: select
    title: "What pattern do you want to display?"
    description: "This pattern will show up in slot_01."
    options:
      - [wvu-triptych, 1]
      - [wvu-diptych, 2]
      - [wvu-media-object, 3]
    include_blank: false
    default: 1
---

• Then, your template could consume this data via <r:page:data name="pattern_name" />

An example of Custom Data with various options:

Again, in Liquid, this process is nearly identical. The only difference is how you incorporate custom data into your templates.

Examples of how you might use Custom Data:

Here are a few ideas:

• To show or hide a section of a page on your site.
  • Imagine you are redesigning a site and, over time, the content authors want to "enable" features on a per-page basis. You could use an if statement and have Custom Data with a Yes or No radio choice to show or hide this feature. The code might look like this:

{% if page.data.show_awesome_feature == "Yes" %}
   <p>If you click "Yes" in Page Properties > Custom Data, this content will show up.</p>
{% endif %}

Then, your template's frontmatter would look like this:

---
layout: default
custom_data_attributes:
  - show_awesome_feature:
    type: radio
    title: "Show the awesome feature?"
    options:
      - "Yes"
      - "No"
    default:
      - "No"
---

• Maybe you need to capture a specific string, but don't want to force users to enter the exact string.
  • For example, imagine you want to capture wvu-triptych, wvu-diptych or wvu-media-object. It'd be a tough sell to get a content author to remember those; however, with Custom Data, we can throw those strings into a select box so it's easy for them to choose one.

---
layout: default
custom_data_attributes:
  - pattern_name:
    type: select
    title: "What pattern do you want to display?"
    description: "This pattern will show up in slot_01."
    options:
      - [wvu-triptych, 1]
      - [wvu-diptych, 2]
      - [wvu-media-object, 3]
    include_blank: false
    default: 1
---

• Then, your template could consume this data via {{ page.data.pattern_name }}.