Blog

Creating Theme Customizations with Config Files

No comments

The following article is intended for theme developers only. If you’re not familiar with HTML, CSS, and JavaScript, it might just look like gobbledygook.

We’ve said it before, but we’ll say it again. One of our favorite features of GiftFold is its endless customization. In this article, we’re going to share a little bit about config files.

Introduction

At the heart of every custom, GiftFold theme lies a settings.xml config file. From this single file, you, oh faithful theme developer, you may not be able to move mountains, but you can:

  • Name, describe, and version your theme – essential for upgrades
  • Create theme customizations (e.g. letting users easily change your theme’s color)
  • And create campaign customizations (e.g. letting users select a mobile layout for a fundraising event)

That Format Tho

While JSON works great for data objects (as in our API), it’s not so great for describing how those data objects should be represented. That’s why we use XML. It’s an extensible markup language (hello) that can give our admins (your users) a consistent experience with your themes.

The XML File

So, now that you know why we use XML, let’s take a look at our config file. Here’s a really simple version which you can nick for your own theme. (Get the Gist on Github.)

<?xml version="1.0"?>
<settings xmlns="http://giftfold.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://giftfold.com/giftfold_theme_settings.xsd">
  <form>
    <customization>
      <name>fund</name>
      <type>string</type>
      <value>Disaster Relief</value>
    </customization>
  </form>
  <theme>
    <customization>
      <name>title</name>
      <type>string</type>
      <value>Organization Name</value>
    </customization>
    <installation>
      <name>freebie</name>
      <version>1.0.0</version>
      <description>A basic config file for your GiftFold theme.</description>
    </installation>
  </theme>
</settings>

Let’s break this down a bit…

The Root Element

This is, quite simply, a settings file. So we ingeniously declared the root element… “settings.” You’ll need to enclose your config file with it (<settings></settings>) so we know where to start and where to end.

And by indicating the XML namespace (xmlns), we know this config file is meant for GiftFold. (By the way, if you want to check out the XSD file for yourself, just follow the xmlns:xsi URL.)

The Form Element

The form element serves one purpose: to create customizations for each donation form (campaign).

For example, in the above config file, we’ve created a custom attribute for our campaigns called “fund.” You can create as many customizations as you want, but be careful not to burden users with too many fields.

Every customization requires the following three child elements:

  • name – What the admin user will see (use lowercase, because we’ll automatically capitalize it when rendering).
  • type – Indicates the type of form control to use (select, string, text).
  • value – The default value which populates the control when a user creates a campaign.

NOTE: If you create a select-type customization, you can use <option></option> to specify drop down items. Just place them after <value></value>.

Form customizations can be accessed in form.liquid with the “form.custom” liquid filter (e.g. {{ form.custom.fund }}) and in receipt.liquid with the “donation.form.custom” filter (e.g. {{ donation.form.custom.fund }}).

The Theme Element

The theme element has two parts: (1) customizations and (2) installation details.

While you might fix the design of your theme, you may also want to give your users some flexibility. Using theme customizations, you can allow users to easily use their own logo, colors, and fonts. These customizations are available to all liquid files, though they are mostly used in theme.liquid (e.g. {{ theme.custom.color }}).

As for the installation element, it indicates the name, version, and description of your theme. It’s essential for allowing users to upgrade their theme.

In Summary

To summarize, the settings.xml config file tells GiftFold how to use your theme. Most importantly, customizations make your theme more accessible to different organizations with different needs.

JonCreating Theme Customizations with Config Files

Related Posts

Leave a Reply

Your email address will not be published. Required fields are marked *