What Is A Templateset?

Customize the look and feel of your Pages using Templates. Our templating system separates the graphic design work of creating pages with your organization's style from the campaign work of setting goals, crafting your message, and creating content.

Templates define everything about the appearance of your pages from your page layout and colors, to the fields displayed in your user forms and the image for your thermometers. Each Page you create in ActionKit combines input from multiple Templates.

A Templateset is just a group of all the available Templates; each ActionKit Page combines input from multiple Templates.

To set a Page's appearance you just select the appropriate Templateset from the dropdown on the Edit Content screen.

How Do I Create a Templateset?

You'll want someone who knows HTML to make changes. Templates are a powerful tool but their flexibility means you can break them!

Before you begin creating templatesets we recommend reviewing the information about managing templatesets to help avoid unnecessary proliferation. You can find other detailed information in the Developer Guide under How To Customize Your Pages Using Templates.

You'll also need to pick an existing templateset to copy. The only way to create a new set is to copy an old one. The Original Templateset is the default we provide with the latest built-in functionality. We recommend that you copy this set, or one of your own that was created from the current Original.

To create a new Templateset:

1 Open your templateset list.

The list of available Templatesets is displayed. The Original Templateset is the default we provide with the latest built-in functionality. We recommend that you copy this set, or one of your own based on the current Original.

2 Copy a templateset.

The only way to create a new set is to copy an old one. Click Copy to the right of the Templateset you wish to start from to create a clone with "copy" appended to the name.

3 Name your new templateset.

On the Change Templateset screen:

  • Name: Name your template. Required.
  • Description: Include how this templateset is different from your others. Required.
  • Language: Default is English. If this will be a foreign language set, select the language from the drop down. Use Templatesets along with Language settings to display pages entirely in another language, including error messages, privacy policy and any other text. Read more about Languages.
  • Github Connection: You can connect a GitHub repository to your Template Set. This allows you to keep your Templateset in GitHub, while automatically sending the changes to ActionKit when you push. Changes made in ActionKit will never be sent to GitHub, it's a one-way connection. Read more about connecting your templateset to a github repository.
  • Custom Templateset Fields: If you have created a templateset field, you'll be able to select it from the drop down in this section. Or click the + to create a new one.

4 Click Save. You will be directed to the Templates screen.

5 Edit your templates.

The Anatomy of a Page documentation describes how the templates work together to form each page type and may help you pick which template you want to modify.

You have a few choices for how you edit your templates:

  • Edit in the ActionKit Admin: You can edit templates directly in the ActionKit admin by clicking on the Template name. The Change Template screen opens and the HTML is displayed. Other templates are available in the drawer on the left of the editor.
  • Edit locally using manual uploads: Download the full set of templates from the Templates screen. Make your edits locally and upload the modified template(s) using the Upload templates files button. Most browsers will allow you to upload multiple templates, but you can also create a zip archive if you are on a slow connection.
  • Edit locally using "Link local files": After downloading the templates, drag and drop the files onto the link local files dialog. As long as you keep this window open, we'll automatically upload the changed files, and try to reload the current preview window. Sorry Safari users, this feature not available.

You can customize your templates using Snippets. You can click to insert most snippets using the snippets menu at the top of the template if you're editing in the admin. Or cut and paste these into your template if you're editing locally.

You can also add your own templates. This does not allow you to create a new page type, but you can re-use the template code in any of your pages.

From this screen you can also select:

  • Settings: Takes you to back to the Change Templateset screen.
  • History: Displays a history of changes to individual Templates with who made the change and the time. Click on a change and then scroll to the bottom or click on "View diff" to see highlighted diffs.

6 Save and preview your changes.

Saving your changes allows you to work on changes to multiple templates before publishing. Templates with changes will be listed under "Changed pages" and marked as "Draft" under status on the Templates page.

Previews are available from the Templates screen and the Change Template page.

On the Templates screen, Use the auto-select to search for a page to preview. If you are using the Link local files or Upload template files, we will try to refresh the preview screen automatically. However, if the refresh doesn't happen automatically you can refresh manually, or click the preview button again.

On the Change Template screen, either click the "Preview" button or click the + to open the Preview drawer on the right hand side of the screen. You can use the auto-select to search for a page to preview. We also try to suggest relevant pages, based on the template you are editing, as well as showing pages you recently previewed.

Once you have a preview window open, you can use the forms, submit actions and navigate to other pages without leaving preview mode. As you make changes to templates, we'll still try to refresh the window automatically. For example, to work on the look and feel of error messages, you could load a Petition page, submit the form with an error and as you make changes to different templates, the preview mode will reload with the errors.


You're still viewing a live page in preview mode. If you make a donation in preview mode a donation is recorded in ActionKit and a charge is made to your credit card.

While you're previewing the changes, you'll see the preview toolbar at the bottom of your screen:

  • Click Switch to see the same page with another Templateset.
  • Click Exit Preview Mode to return to the normal published version of the site.
  • Click Publish to make your changes live for all pages using the Templateset.

You can also preview how a templateset would look on an existing page by appending ?template_set=[TEMPLATE_SET_NAME] to the end of the URL.

For example, let's say we want to see how our templateset "dev" would look like on http://docs.actionkit.com/survey/test/.

We'd type the following URL into the browser:



You can do a lot of things by customizing your Templates, but it's easy to make mistakes. If you make a mistake you can break your Pages in ways that may or may not be obvious to your end users.

Test new or modified Templates before making them public. You can do this by creating a page that uses the Template and taking action on the Page. Unless the changes are minor, you should view the Page in several browsers. If you're logged in as an administrator, you'll see a detailed traceback/error message for related problems to help with troubleshooting.

We recommend following a testing protocol whenever you make any changes to your Templateset. We've outlined a full testing scenario that you can use.

8 Publish.

When you are satisfied with your changes click Publish. Your changes are published immediately and applied to all Pages using this Templateset.

How Have Other Clients Managed Templatesets?

Conditional Content

One of the most common customizations is adding conditional content, e.g. {% if %} {% else %} {% endif %}.

For example, say you want to include a specific CSS stylesheet for pages that are part of a special project:

{% if page.name == "special_project" %}
    <link href="/css/special.css" rel="stylesheet">
{% else %}
    <link href="/css/normal.css" rel="stylesheet">
{% endif %}

Conditional statements can be used to check all kinds of details, including:

  • Custom page fields, page tags, name, etc.

  • Hostname. Have different brands for different hostnames?

    {% if "specialproject.com" in request.get_host %}..special project code..{% endif %}

  • Query parameters. You can pass data with query parameters, but these must be handled with extreme care. Using query parameters as part of conditional statement is fine:

{% if args.brand == "special_project" %}..special project code..{% endif %}

But do not directly render query parameters, as that could introduce cross-site scripting vulnerability: "(Danger!) Welcome to {{ args.dont_do_this }}. (Danger!)"

Using Custom Page Fields to Enable Features includes a thorough walkthrough of conditional content and custom page fields, see also Using Custom Templateset Fields to Simplify Changes

Other approaches can help organize template code or help avoid duplication. For example, use {% store %} to consolidate custom conditional logic into one place that's easy to change, such as the top of a template:

{% store as specialObj %}
   {% if page.custom_fields.is_special %}
         var myObj = { name: 'special', amount: '42' }
   {% else %}
         var myObj = { name: 'not so special', amount: '10' , default: true}
   {% endif %]
{% endstore %}
  {{ specialObj }}

Want to change how your templates display data such as products or candidates? You can conditionally filter or sort data to match your needs.

For example, the built-in Original templateset displays any products assigned to your page, but the sort order of products isn't documented:

{% for product in products %}

To sort products by price or name instead, you can use a snippet to re-order the list of products based on the value of a custom field, and default to ordering by amount:

{% for product in products|dictsort:page.custom_fields.product_sort_order|default:'amount' %}

If you're interested in making your templateset more reusable but need some advice on implementation, get in touch with ActionKit support.

Using Page Fields To Trigger Layout or Form Variations Within A Templateset

This technique is most useful if you have a few variations for pages that all use the same wrapper. for example, you might have two petition form layouts that you use regularly with your standard wrapper. Or you may have three fields that you often add to your user forms.

You can use custom page fields to "turn on" optional elements in your templates without creating a new Templateset for each variation.

For example, if you sometimes suppress the tell-a-friend widget on the first screen for your petition pages:

  • Create a new Templateset titled "Petition without taf" and remove the in-line taf code from the petition template. The page creator would select "Petition without taf" or your standard Templateset if they wanted to suppress or show the taf, respectively. Or
  • Create a page field, "suppress petition taf" and add some code to your default Templateset to tell ActionKit to hide the taf only if the page creator enters "1" in the page field when creating the page.

Both approaches work, but if you use the first approach you then need to maintain both templatesets. and it can be hard to keep track of the variations between sets if you have a second or third field that you also include sometimes (e.g. phone).

The second approach can lead to a long list of page fields if you have a lot of variations. In either case it's a good idea to develop naming protocols and some basic documentation for your templatesets and page fields.

Here's an example of what the code might look like if you were to use the same approach to include an occupation field in the user form based on a page field. If you're using the Original Templateset or one modeled on this, you can customize the user form from the Edit content screen instead. Regardless the example demonstrates the concept above.

You might set up the field field as follows:

  • Create a page field called add_occupation_to_form.

  • Edit the User form template in your default Templateset.

  • Add something like the following:

    {%if page.custom_fields.add_occupation_to_form == "yes" %}
      <div class="ak-field">
        <input type="text" name="add_occupation_to_form"  id="add_occupation_to_form">Occupation:</input>
    {% endif %}


    This assumes I already have a custom user field named occupation. If not, I'd have to create it first from the user's tab.

  • Test it by creating a page, selecting the page field at the bottom of step 1, and enter "yes" as the value. Make sure the form shows the occupation field.

  • Document this and share with page creators so they know what the field does and how to use it.

You can use this approach for all kinds of variations. If you have three fields you often add to pages, create one page field for each and the campaigner can add all or some of them using this approach.

Here are some other examples of how you might use this:

  • Add an optional layout element, like a pull out quote or an image.
  • Add a custom action field or survey question.
  • Allow your campaigners to add a custom action field themselves by entering the action field information - you'd just have defined where and how it displays in the form.
  • Make your thermometer amount increase if you've already hit the original goal.
  • Include a lightbox with page specific content.
  • Add social media sharing options and page specific default messages for sharing.

Using Templateset Fields To Set Styles Across A Templateset

Templateset fields are a type of custom field, like custom page fields or user fields. They're associated with the templateset and allow you to make templateset-specific customizations.

For example, if your site used a few different templatesets which were mostly similar but used different colors, you could define a custom templateset field for heading color, and reference it from within your template code. You could then copy the templateset and choose a different color without making any changes to the code.

Templateset fields you've created are available on the Settings screen for each templateset.


If you don't see a Custom Templateset Fields section on this screen, no custom templateset fields have been created for your organization.

To add custom templateset fields, select Custom Templateset Fields under Appearance on the sidebar on the right on the Pages Tab and click Add allowed templateset field. Enter the name and other settings for your templateset field and then save.

To use the field in your templateset, go to the Settings screen for your templateset to set the values for the templateset fields. And then include {{ templateset.custom_fields.YOUR_FIELD_NAME_HERE }} in your templates to use the field.

The Original templateset comes with a selection of default fields, which you can view and edit by making a copy of the Original templateset.

Using Page Type To Trigger Variations

You can use one Templateset to display different fields based on the page type. to do this include something like the following in the user form template:

{% switch page.type %}
  {% case 'donation' %} [...one hide_by_default tag...]
  {% else %} [...different hide_by_default...]
  {% endswitch %}

The relevant page types in ActionKit are: Petition, Letter, Survey, Donation, Signup, Call, WhipCount, LTE, Unsubscribe, RecurringDonation, EventCreate, EventSignup, RecurringDonationUpdate, RecurringDonationCancel.

Defining Master Templates

You can use a template from one Templateset in another set. This technique allows you to define a master for a particular template so you only need to make edits in one place, even if you have more than one Templateset.

For example, if you only have one LTE layout, you could define the layout in your default Templateset, and have any additional sets pull the layout from the default set using something like this (where the default set is called "Master_templates"):

{% include "Master_templates/survey.html" %}

See also mirroring parent templatesets.

How Can I Preview A Templateset On A Page Before I Apply It?

You can also preview how a templateset would look on an existing page by appending ?template_set=[TEMPLATE_SET_NAME] to the end of the URL.

For example, let's say we want to see how our templateset "dev" would look like on http://docs.actionkit.com/survey/test/.

We'd type the following URL into the browser:


Connecting a Templateset to a GitHub Repository

The "Change Templateset" screen allows you to connect a GitHub repository to your Templateset. Keep your Templatesets in GitHub, but automatically send the changes to ActionKit when you push. Changes made in ActionKit will never be sent to GitHub, it's a one-way connection.

To connect a repository, you'll need to synchronise your files, add a GitHub repository and settings to ActionKit, and install the webhook and deploy key.

Synchronise Your Files

It is important that your GitHub repository and ActionKit contain the same versions of the Templateset files when you initialize the connection. ActionKit won't synchronise them for you.

If you don't have your templateset in a repository yet:

  • Download the ActionKit Templateset
  • Add the Templateset to the repository
  • Configure the connection

If you do have your templateset in a repository, you need to make sure ActionKit and the repository have the same files. Here's one way to do that:

  • Download the ActionKit Templateset
  • Commit any changes to Git and push to GitHub
  • Upload the merged version to ActionKit
  • Configure the connection

You can find the download link on the Template Picker page.


Add A Github Repository And Settings

Now that you are sure you have the same versions in both places, you can configure the connection to GitHub. Here is a description of the fields you need to provide:

Setting Description
Repository Select from the list of GitHub repositories ActionKit knows about. Use the addanotherimg to add a new Repository.
Path The path in the repository to this Templateset. If your Templateset is the only directory in the repository, leave this empty.
Live branch Changes to this branch will be saved to the Templateset when they are pushed to GitHub. Defaults to "master".
Preview Branch Changes to this branch will be saved as previews when they are pushed to GitHub. Defaults to "preview".

To add a new Repository, use the addanotherimg. You'll need to fill in the following fields:

Setting Description
Owner The username at GitHub that owns the repository.
Repository The name of the repository at GitHub.
Private Is this a private repository? We need to know.

The "Owner" and "Repository" are easy to find from the URL of your repository at GitHub. If your Templateset is in a repository accessible at:


"aaronelliotross" is the owner. "actionkit-templatesets" is the repository.

All changes pushed to GitHub on a repository will be sent to ActionKit. We'll use these settings to figure out which commits should be applied to this Templateset. The owner and repository fields will be matched against the repository, the branch will be matched against the branches configured here, and the filepath of the modified file will be checked against Path.

Here's a quick example. In your GitHub account "yourloginname", you have a repository "actionkit" and in that repository, you have a directory named "templatesets", where each templateset has it's own directory:

   --> actionkit/
         --> templatesets/
              --> Blue/
                 --> wrapper.html, ...
              --> Red/
                 -->  wrapper.html, ...

To connect the Red templateset, you'd enter a Path of "templatesets/Red", and configure the repository with the owner "yourloginname", and the repository "actionkit".

Once you've got your Repository, Path and Branches configured, you'll need select an option to install the webhook and deploy key.

Install The Webhook And Deploy Key

You can either let us automatically install the webhook and deploy key, or if you are not comfortable granting access to the ActionKit Templateset Integration application, install them yourself manually.

Automatically configuring the connection requires granting ActionKit read / write access to your repositories, see below for more details.

Save Manually

To manually install the settings on GitHub, save your changes with the 'Save and install at GitHub Manually' button.

The resulting page has instructions, as well as settings specific to each Templateset you'll need to get the connection working.

The basic steps, on GitHub, are:

  • Find the settings for the repository you want to connect.
  • Add a webhook, using the URL and secret key we provide on the manual install page.
  • Add a read-only deploy key, using the public key we provide on the manual install page.

Save With oAuth

To use oAuth to install the webhook and deploy key, Actionkit will need you to grant it permission via oAuth.

Once you've granted permission, we'll automatically install both the webhook and the deploy key. You'll see ActionKit Templateset Integration as the name of the oAuth application. You can verify the settings we've added in the repository settings menu.

Use the 'Save and install at GitHub with oAuth' button to have us install the settings automatically.

GitHub's API requires that we ask for two scopes (oAuth permissions):

  • write:repo_hook, access to read / write webhooks on repositories you have access to.
  • repo / public_repo, read / write access to repositories you have access to.

If the repository you want to connect is private, we'll ask for access to your private repositories. If it's public, we can limit our request to public repositories.

NOTE: We don't need full access to your repositories, but GitHub doesn't provide a scope for installing deploy keys, nor a way to revoke scopes that we can access via the API. We do not store the oAuth token once we've used it - we revoke it after we're done - but the application must remain authorized or the deploy keys will be deleted.

Let us know if you have trouble with getting the connection setup! There are a lot of possible configurations and we probably haven't seen them all yet.

Once we've got your permission, we'll install the Webhook and send you back to the Templateset template editor.

Debugging Problems With The Connection

  • Check that the WebHook is getting a 200 response in GitHub. You can click on the WebHook URL to see recent requests and responses. If they are not succeeding, check the URL, copy the signature again, and re-send a request.
  • Check that the deploy key is installed on the right repository. You can copy the public key from the installing manually page, if it's missing.
  • Check that the Paths match.
  • Check that the branches exist in the repository and match.
  • Still stuck? Submit a support ticket.

Using The Connection To Change Preview Templates

Changes you push to the preview branch will create preview templates, visible on the Template Picker page under "Unsaved Changes".


You must use the Preview button to enter preview-mode.

However, once you are looking at a Page with the previews, if you push additional changes, simply reloading will load the new version of the preview. There is, of course, a delay between your push to GitHub and the time ActionKit gets notified.

Read more about previewing changes.

Using The Connection To Push Changes Live

If you push changes to the master branch, they will immediately be applied to your Templateset and to all pages using that Templateset. There is no undo button, though you can always use Git to push a reversion of your changes.