Using JS/Python Contexts in ActionKit

General Idea

We needed a way to do JS embedding of AK code, including user recognition, validation, etc. Briefly the way we do that is:

  • A client loads a static page. That page loads /samples/actionkit.js and has an action form (usually named 'act').
  • actionkit.js defines a bunch of JavaScript functions and attributes in an actionkit object, mostly in actionkit.forms and actionkit.utils.
  • After the <body> tag, the client’s HTML calls actionkit.forms.initPage().
  • After the </form> tag on their action form, the client needs to call actionkit.forms.initForm(‘act’).
  • initForm inserts a <script> element in the page pointing to some server side code (/context/).
  • The server side code returns JavaScript in the format callback_function (JSON data).
  • The javascript callback function runs, and does things like “not bob?”, prefilling, and validation. It also processes ak-templates, which look like <script type=”text/ak-template”>[% foo %]</script>

Even more simply: the page loads Javascript, which loads other JavaScript that has dynamic info from the server. It's AJAX-y (JSONP is the buzzword for it), though the asynchronous calls are made in a cascade on page load and page submit rather than in response to particular user events like key presses or mouseovers. We use JSONP rather than straight AJAX so client forms can pull in context from any site, not just from pages at ActionKit (AJAX has to be same-domain).

Example Usage


{% extends "./wrapper.html" %}{% load actionkit_tags %}

{% block script_additions %}
<script type="text/javascript">
function toggleChooser(on)    { ... }
function countWords(textarea) { ... }
function commify(n)           { ... }
function abbreviate(word, maxLength) { ... }
$(window).load( function() { ... }
$("input[name=media_target]").change(function() { toggleChooser(false) } );
{% endblock %}

{% block content %}
<form class="ak-form" name="act" method="POST" action="/act/" accept-charset="utf-8">
<input type="hidden" name="page" value="{{ }}">

<div class="ak-grid-row">
    <div class="ak-grid-col ak-grid-col-12-of-12">
        <h2>{{ page.title }}</h2>

<div class="ak-grid-row">
    <div class="ak-grid-col ak-grid-col-6-of-12">

        {% if page.custom_fields.featured_image %}
        <img class="ak-featured-img" src="{{page.custom_fields.featured_image}}">
        {% endif %}

        <div class="ak-styled-description ak-text-expander">
            {% include_tmpl form.introduction_text %}
        <a href="#" class="ak-read-more ak-mobile" data-lines="10">Read more</a>

        <div id="lte-prelim"></div>

        <div id="user_info_prompt">

        <div id="lte-help"></div>
        <script type="text/ak-template" for="lte-help">

                                    {% if form.talking_points %}
                    <div class="lte-help-head">
                        Talking Points
                        {% include_tmpl form.talking_points %}
                {% endif %}
                {% if form.writing_tips %}
                    <div class="lte-help-head">
                        Writing Tips
                        {% include_tmpl form.writing_tips %}
                {% endif %}
                {% for letter in form.cannedletter_set.all %}
                    <div class="lte-help-head">
                        Sample: {{ letter.subject|truncateletters:"20" }}
                {% endfor %}


    <div class="ak-grid-col ak-grid-col-6-of-12">
        {% include "./progress_meter.html" %}

        <script type="text/ak-template" for="user_info_prompt">
            [% if (incomplete) { %]
                <p>Please enter your information so we can find newspapers for you to contact.</p>
            [% } %]
        <div class="ak-styled-fields {{templateset.custom_fields.field_labels_class|default:"ak-labels-overlaid"}} {{templateset.custom_fields.field_errors_class|default:"ak-errs-below"}}">
            {% include "./user_form_wrapper.html" %}

        <div id="media_target"></div>

        <script type="text/ak-template" for="media_target">

            [% if (!incomplete) { %]
                <p>Choose a newspaper to send a letter to:</p>

            var headers = {
                "local": "Local Newspapers",
                "regional": "Regional Newspapers",
                "national": "National Newspapers"

            var mediaTargets = actionkit.context.mediaTargets || {};
            var mediaTargetTypes = ['national', 'regional', 'local'];
            for (var j = 0; j < mediaTargetTypes.length; j++) {
                var mediaTargetType = mediaTargetTypes[j];
                var targetsOfType = mediaTargets[mediaTargetType];
                if (targetsOfType) {
                    <div class="ak-newspaper">

                    var shade = true;
                    for (var i = 0; i < targetsOfType.length; i++) {
                        var mediaTarget = targetsOfType[i],
                        targetId = "media_target_" +,
                        name = abbreviate(, 30),
                        label = "<a>" + name + "</a>";
                        if (mediaTarget.website_url) {
                            label = "<a target=\"_blank\" href=\"" + mediaTarget.website_url + "\">" + name + "</a>";
                        shade = !shade;
                        <div class="[%= shade ? "shaded" : "" %] ak-newspaper-row">
                            <div class="ak-newspaper-title">[%=label%]</div>

                                <label for='[%=targetId%]'>
                                    <input class='media_target' id='[%=targetId%]' value='[]'
                                    type='radio' name='media_target' onclick='javascript:toggleChooser(false)'>

                                <div class="number"><strong>Circulation:</strong> [%=commify(mediaTarget.circulation)  %]</div>

                                [% if (actionkit.context.show_phones && { %]

                                    <div class="nowrap"><strong>Phone:</strong> []</div>

                                [% } %]
                                <div class="number"><strong>Sent:</strong> [%=mediaTarget.sent%]</div>
            } %]


        <div id="lte-letter"></div>
        <script type="text/ak-template" for="lte-letter">
            [% if (!incomplete) { %]
                <table class="ak-styled-fields">
                    <tr id="to_target_row" style="display: none;">
                            <span id="to_target_name"></span>
                            <span style="font-size: smaller"> &nbsp; <a href="#" onclick="javascript:toggleChooser(true)">change</a></span>
                        <td><input id="letter_subject" type="text" name="subject" size="40"></td>
                        <td class="textarealabel">Message</td>
                            <textarea id="letter_text" name="letter_text" class="count[250]"></textarea>
                            <div class="wordCount"><strong>0</strong> Words.  Most newspapers only consider letters of 250 to 350 words.</div>
                        <td> </td>
                        <td>Your name, address and phone number will be added as a signature.</td>
            [% } %]

        <div id="lte-submit"><button type="submit" class="ak-styled-submit-button">Submit</button></div>



{% endblock %}


There's a large amount of code that makes contexts work, and it can be tough to follow the process because it jumps back and forth between client and server side. This section outlines the basic steps you need to take to use contexts in your pages.

Main Files And Functions Involved In Contexts

This file adds the actionkit JS object to the window object, and has a number of methods and attributes under the headings forms and utils. The methods come together to make a fairly linear chain of calls and related callback methods, where the call causes a <script> element to be created, and the callback is what's executed as the src of that element, wrapping the JSON that the original call requested.
This holds the jquery-fu that gets used to prefill whatever form is currently being acted on, if want_prefill_data and prefill are present in whatever JSON a particular callback is operating on. Prefilling usually happens from query string args after a user enters invalid data that’s only caught by the server. There’s also prefilling from data returned by the server, in the events tool.
context() returns user info and other data in the callback( JSON ) syntax, so that it gets executed on the client side.
Returns error messages in the user’s language, in the same JavaScript format as context()’s response.
Returns thermometer/progress-against-our-goal data, if none was cached and returned by context().
The template file is where you'll add javascript that uses the context data. This happens via a series of blank divs combined with matching ak-template script blocks, as in the above examples.

Code You'll Need To Write

The code that you will actually author and control will all live in your template file. Within your template(s), interactions with context data will happen in one of two ways: via the code in actionkit.js and prefill.js, and via your own ak-template blocks, where you'll be able to execute javascript that adds content to divs throughout your template file.

Executable ak-template Blocks

You can put any number of ak-template blocks into your template page, and each one will allow you to set the content of a matching div element. Divs and their templates are matched by setting the id of the div and the 'for' attribute of the ak-template script tag, like this:

<div id="all_fields"></div>
<script type="text/ak-template" for="all_fields">
<p><b>Current context:</b></p>

What appears inside the script tag will be processed into the innerHTML of the div. You can put raw HTML inside the script tag, as well as executable javascript. The javascript must be wrapped in a special bracketing syntax to get picked up by actionkit.utils.template():

<div id="sector_x"></div>
<script type="text/ak-template" for="sector_x">
[% if (actionkit.context.show_x) { %]
[% } %]

Executable blocks will just get the [% … %] wrapping, while substitution tags will get [%=var_foo%]. You can use anything that's available to you in the context, but make sure you've planned for each variable you use from the django side by placing it into the context dict in your Processor class's context() method.

Flow Of Execution For A Context

The execution of contexts is a collaboration between the client side Javascript code, and the methods inside the ActionKit codebase. Below is a reference for the flow of execution for a context usage, primarily focused on the Javascript methods and processing side of the equation.

  • Request is made to apache; Template file is found, served with wrapper.
  • Subsequent request comes in for /samples/actionkit.js.
  • actionkit.js:
    • Adds the actionkit object to the window object.
    • Adds utils and forms to window.actionkit.
    • Adds a large number of methods and attributes to utils and forms.
  • wrapper.html (line 60) calls actionkit.forms.initForm('act'):
    • forms.initForm() (line 748 of actionkit.js):
      • forms.setForm() (line 703) sets the form element that utils and forms methods will work on.
      • Sets the form's onsubmit to a function that will run forms.tryToValidate()
      • Runs forms.loadPrefiller() if prefill and want_prefill_data are in the args. That loads /samples/prefill.js into the document head with forms.createScriptElement().
      • Calls forms.loadContext(), which:
        • Calls forms.beforeContextLoad(), which checks for some event related args.
        • Sets forms.onContextLoaded as the callback function that will be used to process what is returned from the server as JSON.
        • Sets a number of contextArgs values from ak.args, ak: form_name, action_id, akid, rd, want_progress, template, want_prefill_data.
        • Sets contextArgs.required to forms.required(), which returns a list of required names based on what's in the 'required' element in the form.
        • Creates a contextUrl from the contextRoot and the contextArgs, and uses forms.createScriptElement to load that contextUrl as the src of a script element in the document head.
  • Request comes in from the browser for the constructed contextUrl, which will be of the type /context/?a=b&c=d...
  • ActionKit code does the following (paraphrasing here--the contexts interface is stable, but AK internals may change):
    • Finds the specific page object that the contextUrl referenced.
    • Creates a blank dictionary (python's associative array datatype) to store context info in.
    • Checks for required fields in the submission, and for this page.
    • Checks for language id and custom field info for this page.
    • Checks for any page-type specific fields, like media targets for LTEs.
    • Adds all that info to the context dictionary.
    • Renders that context dictionary as a JSON string.
    • Returns the JSON, wrapped by the callback function specified, as the executable src of a <script> tag.
  • The text/javascript content returned by the server is run, as it's the src of the <script> element that got created via forms.createScriptElement().
  • Since the generic callback for forms.loadContext() is forms.onContextLoaded(), that runs with the JSON as its argument.
  • forms.onContextLoaded(), line 242 in actionkit.js:
    • If ak.context is already set, returns nothing; otherwise sets ak.context to the JSON argument it got.
    • Finds out whether it can recognize the user based on the info it has.
    • If it can, puts the akid into a hidden input and hides the user form.
    • If it can't, shows the unknown user form.
    • Appends several fields as hidden inputs, if they're present in the context.
    • Runs forms.onTargets() if there are targets.
    • Sets context.args to ak.args and adds some methods to context.
    • Runs forms.loadProgress() if necessary.
    • Selects all templates in the page (script tags with the type 'text/ak-template'), and runs forms.doTemplate(context, template) on each.
    • forms.doTemplate() does the following:
      • Runs the context and template through utils.template, which:
        • Generates a cached function based on the javascript in the ak-template
        • Places the output of that function into the innerHTML of the div that has the id which the ak-template section's for attribute lists.
    • Prefills the form if possible.
    • Runs forms.loadText(), which will perform internationalization on some of the context's strings if necessary/possible.
    • Runs forms.handleQueryStringErrors(), which packs up errors and messages into ak.errors, and then runs forms.onValidationErrors()
    • forms.onValidationErrors() does:
      • Clears existing errors from the form.
      • Marks the controls which have errors.
      • Marks the labels to those controls.
      • Marks the form with the class name contains-errors

Function Reference

Below is a guide to the various javascript object methods and attributes that are available via the context system.

Attributes And Shortcut Functions

 Context from server
actionkit.form:The action form (DOM element, not jQuery object)
 Error messages (in user’s language)
actionkit.args:Query string args
$log:Log to console (doesn’t crash on IE)
$sel:Search like jQuery’s $(), but limited to current form if there is more than one



contextRoot:static value: '/context/'
 everything in validators


  • Takes an error name like 'card_num:invalid'
  • Returns a capitalized error string
  • Events Only
  • Runs beforeContextLoad
  • Adds action_id, akid, rd, want_progress, template, want_prefill_data, url to contextArgs
  • Uses a random number to keep ak from caching the response
  • Creates a script element from contextUrl
  • pulls in the prefill script, /samples/prefill.js, into a script element
  • pulls in /progress?page= page id & form_name & callback = onProgressLoaded
  • creates a script element that's an ak-template for 'progress'
  • runs forms.prefill() if ak.forms.awaitingPrefill
  • If there's a context and prefill data, use the prefill data, else use the args
  • If there's a form, use setForm
  • Use $().deserialize() to set the form values
  • Use a jquery each() loop to set checkbox values
  • brings in translated errors from /text/ using the same script-element technique as loadContext()
  • sets forms.text to the input, is the callback for loadText
  • creates a <script> element consisting of an src that is the url passed in, and any additional attributes
  • maintains a callback_id counter and a var 'actionkitCallback'+callback_id
  • registers a callback with the window obj
  • adds the callback to args via args.callback = 'window.'+callback_name
  • creates a script element via a url+args
  • if there's no form in ak.args.form_name, do nothing
  • for each key in actionkit.args like ^(error|message)_, put them into ak.errors
  • if utils.hasAnyProperties( the errors ): ak.forms.onValidationErrors( the errors )
  • is the callback for forms.loadContext()
  • takes a context as an arg
  • if ak.context is already set, returns nothing
  • otherwise sets ak.context to the arg
  • finds out whether it can recognize the person based on the info it has
  • if the person is recognized, stick the akid into a hidden input and hide the user form
  • if they're not, show the unknown user form
  • append several fields as hidden inputs if they exist
  • run forms.onTargets() if there are targets
  • sets context.args to ak.args, adds some functions to context
  • runs loadProgress if necessary
  • selects all the templates in the page
  • for each, runs forms.doTemplate(context, template)
  • prefills if it can
  • runs forms.loadText()
  • runs forms.handleQueryStringErrors()
  • runs the supplied context and element through utils.template()
  • makes the output the innerHTML of the element
  • does some pluralization, adds checkbox and listing html to 'target_checkboxes' element
  • events only
  • events only
  • if there's an akid, store it as referring_akid
  • if there's no akid, log the person out and redirect to their next location
  • otherwise, just strip the akid and rework the query string without it
  • adds 'js' class to the document body
  • clears some window caching
  • loads firebug lite in IE if debug is on
  • sets the current form that ak.form is acting on
  • takes a form name
  • sets the form via setForm
  • if ak.form.onsubmit isn't set, sets it to a function that runs tryToValidate
  • if the prefill is on, run loadPrefiller()
  • run loadContext()


  • email
  • taf_emails
  • zip
  • postal
  • phone
  • mobile_phone
  • home_phone
  • work_phone
  • emergency_phone
  • phone
  • date
  • time



  • URI encodes a string and returns it
  • turn an object into an escaped query string
  • takes the url args and returns them as an object
  • creates a div
  • adds a hidden input tag to a div as the first child
  • is called by appendHiddenInput
  • sticks a hidden input with name/value in the current form
  • turns a list into a dict/hash
  • returns the value of an attribute for a given element
  • used in onProgressLoaded, handleQueryStringErrors, doTemplate, validate, setForm
  • runs through a list of properties, returns true if any are present
  • returns a list
  • used in forms.required
  • returns the value of an element
  • used in,, forms.validate
  • pass a function name and a parameter list, it'll return the eval'd version of same
  • used in forms.validate
  • uppercases and the first letter of a string passed to it
  • used in forms.errorMessage, forms.onContextLoaded
  • commifys a number
  • used in forms.onContextLoaded
  • takes a string and data
  • looks for the result in a cache
  • otherwise processes the result through a generic function
  • which returns a js-safe version of the string