settings.html

The settings.html file is rendered on the Customize theme page of the Haravan Admin. The Customize theme page allows users to easily customize the look-and-feel of their shop without having to dive into the theme's HTML, CSS, or Liquid code.

The settings.html and settings_data.json files are found in the config folder of a theme. The latter file stores the settings that the user selected in settings.html in JSON format.

• The Settings Object
• Markup
• Input Types
• Special CSS Classes
• Customize theme page considerations
• Requirements for the Theme Store

The Settings Object

The values of the settings.html inputs can be accessed in your Liquid templates and stylesheets by appending the name attribute of the input to the settings Liquid object. For example, you may have a text input in settings.html that looks like this:

<input type="text" name="sales_text" value="" /> 

The value of this text input can be output using the following format:

{{ settings.sales_text }}

The settings object can be accessed in any of the Liquid templates in your theme. If you're looking to access settings in a CSS file or a JavaScript file, you can do so by appending a .liquid extension to their file names. For example, if you have a stylesheet named style.css, you would change it to style.css.liquid.

Markup

The settings.html file is validated before being saved to make sure it follows a few rules. You cannot use any Javascript and you can't define any custom CSS styles. It is also run through an XML parser to make sure it's a valid XML fragment.

Input Types

settings.html accepts the following type of HTML inputs:

Single-line Text Fields

Useful for capturing short strings, such as URLs, social media usernames, and sales banner text. When using single-line inputs, be sure to include the value attribute.

Input

<tr>
    <th>
        <label for="my_text">Single-line Text</label>
    </th>
    <td>
        <input type="text" name="my_text" value="" />
    </td>
</tr>   

Multi-line Text Areas

Useful for capturing larger blocks of text, such as embed codes. When using multi-line inputs, be sure to include the value attribute.

Input

<tr>
    <th>
        <label for="my_textarea">Name of this setting</label>
    </th>
    <td>
        <textarea name="my_textarea" cols="60" rows="5" id="my_textarea" value="" />
    </td>
</tr>

File upload

Useful for uploading assets to a theme, such as logo images, favicons, and slideshow images.

You can use the attributes data-max-width and data-max-height to define a maximum size for the image. Haravan will maintain the aspect ratio of the uploaded image while constraining it to those maximum dimensions.

Input

<tr>
    <th>
        <label for="my_file">File Upload</label>
    </th>
    <td>
        <input type="file" name="logo.png" data-max-width="500" data-max-height="300" />
    </td>
</tr>        

Files uploaded through settings.html are placed in the theme's assets folder. The name of the saved file is not determined by the original file, but rather by the name attribute of the file input tag. For example, the file uploaded through the example above would be saved as logo.png. Furthermore, Haravan will convert the image to the type specified in the name attribute.

Radio button

Useful for presenting a limited amount of options to the user; for example, selecting the alignment of the logo.

Input

<tr>
    <th>
        <label for="my_radio">Radio Buttons</label>
    </th>      
    <td>
        <input type="radio" name="logo_option" value="1" /> Option 1
        <input type="radio" name="logo_option" value="2" /> Option 2
    </td>
</tr>

Select drop-down

Useful for presenting a large number of options to the user; for example, selecting the number of products to show on the product page.

Input

<tr>
  <th><label for="my_dropdown">Select drop-down</label></th>
  <td>
    <select name="my_dropdown">
      <option value="1" selected="selected">1</option>
      <option value="2">2</option>
      <option value="3">3</option>
      <option value="4">4</option>
    </select>
  </td>
</tr>

Checkbox

Useful for toggling preferences on or off; for example, showing/hiding elements on a page.

The values of checkboxes are always forced to be 1, and hidden fields are inserted by Haravan in the Customize theme page that is generated for each checkbox to allow for false values to be submitted appropriately.

Input

<tr>
    <th>
        <label for="my_checkbox">Checkbox</label>
    </th>      
    <td>
        <input type="checkbox" name="my_checkbox" value="1" />
    </td>
</tr>

Special CSS Classes

For some inputs, you can apply a CSS class to have it render a special Theme Setting with pre-populated values.

color

Applying the CSS class color to an input of type text will generate a color picker once settings.html is rendered.

Input

<tr>
    <th>
        <label for="my_color">Color Picker</label>
    </th>
    <td>
        <input type="text" name="my_color" class="color" value="" />
    </td>
</tr>        

font

Applying the CSS class font to a select will generate a drop-down that is automatically filled with a list of web-safe fonts.

Input

<tr>
    <th>
        <label for="my_font">Font</label>
    </th>
    <td>
        <select class="font" name="my_font" />
    </td>
</tr>        

collection

Applying the CSS class collection to a select will generate a drop-down that is automatically filled with all of the collections in the shop. The output of the selected option is the handle of the collection.

Input

<tr>
    <th>
        <label for="my_collection">Collection</label>
    </th>
    <td>
        <select class="collection" name="my_collection" />
    </td>
</tr>        

blog & page

Applying the CSS class blog or page to a select will generate a drop-down that is automatically filled with all of the blogs or pages in the shop. The output of the selected option is the handle of the blog or page.

Input

<tr>
    <th>
        <label for="my_blog">Blog</label>
    </th>
    <td>
        <select class="blog" name="my_blog" />
    </td>
</tr>        

linklist

Applying the CSS class linklist to a select will generate a drop-down that is automatically filled with all of the link lists in the shop. The output of the selected option is the handle of the link list.

Input

<tr>
    <th>
        <label for="my_linklist">Linklist</label>
    </th>
    <td>
        <select class="linklist" name="my_linklist" />
    </td>
</tr>        

snippet

Applying the CSS class snippet to a select will generate a drop-down that is automatically filled with all of the snippets in the shop. The output of the selected option is the name of the snippet, without the .liquid extension.

Input

<tr>
    <th>
        <label for="my_snippet">Snippet</label>
    </th>
    <td>
        <select class="snippet" name="my_snippet" />
    </td>
</tr>        

Customize theme page considerations

Handling "None" selections

A theme will rarely call on a hard-coded page, collection, or blog. Instead, they typically look at the theme's Customize theme page.

In other words, you would not see objects being loaded as follows:

{% for product in collections.frontpage.products %}
  {% include 'product-grid-item' %}
{% endfor %}

Instead, you would load a page, collection, or blog selected through the settings object:

{% for product in collections[settings.fp_collection].products %}
  {% include 'product-grid-item' %}
{% endfor %}

Theme customizations with any of the special CSS classes will allow you to pick among existing published objects.

It is important to note that a Theme Setting can be set to None as well.

This does not return a string with the value None - instead, it returns an empty string in your theme's config/settings_data.json file:

"fp_page": "",

To determine if the Theme Setting for the page, blog, or collection is empty, compare your the appropriate settings attribute to blank as follows:

{% if settings.fp_page == blank %}
  <!-- The merchant does not want to add a page here. His fp_page theme setting was set to None. -->
{% endif %}

An unless statement would work as well:

{% unless settings.fp_page == blank %}
  {% assign page = pages[settings.fp_page] %}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content }}</div>
{% endunless %}

The example below would not work, as empty strings are truthy in Liquid. If your settings.fp_page is an empty string, then {% if settings.fp_page %} will be true, resulting in empty elements on the page.

Input

{% if settings.fp_page %}
  {% assign page = pages[settings.fp_page] %}
  <h1>{{ page.title }}</h1>
  <div>{{ page.content }}</div>
{% endif %}

Output

<h1></h1>
<div></div>

Handling non-existent settings

There may be cases where a Theme Setting is set to an object that used to exist, but was deleted or hidden. From a theme's point of view, a hidden resource is the same as one that doesn't exist.

For example, you may have a Theme Setting that is set to frontpage:

"fp_page": "frontpage",

After this is set, the frontpage page could be deleted or hidden by the user. You can account for this situation by performing two checks:

{% unless settings.fp_page == blank or pages[settings.fp_page].empty? %}
{% assign page = pages[settings.fp_page] %}
<h1>{{ page.title }}</h1>
<div>{{ page.content }}</div>
{% endunless %}

We first check if the Theme Setting is set to a value that is not blank, then check if it is still accessible in the shop.

Requirements for the Theme Store

If you're looking to submit your theme to the Theme Store, the settings.html template of your theme must meet the following conditions:

• Theme customizations on the Customize theme page should not be overwhelming or tedious
• Must not include a setting to remove {{ powered_by_link }}
• Logo upload must work with images of different aspect ratios (for example, landscape vs. portrait)
• Include a setting for uploading a custom background image
• Include settings for social icons. Customers must be able to enter the URL of their social pages, and the URL must be applied to their respective icons
• Settings to change fonts for headings and regular text