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 %}
...
<script>
  {{ specialObj }}
  $('input[name=amount_other]').val(myObj.amount)
</script>

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>
    </div>
  {% endif %}
  

  Note

  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.

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.

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 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 . 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:

https://github.com/aaronelliotross/actionkit-templatesets/

"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:

github.com/yourloginname/
  |
   --> 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.

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.