Embedding

What & Why

When you create a page, the default is to host your page with ActionKit.

You can customize your page in lots of ways by editing the relevant template as described in Customizing Pages with Templates. While ActionKit Hosted Pages provide a lot of flexibility, you might still want to host a page on your own site - for example, to integrate with a content management system or custom tools you've built.

We've made it easy for you to access ActionKit's functionality, even from pages hosted outside of ActionKit, with embedding. The embedding system lets you put our form (with our JavaScript and submitting to our server) inside one of your HTML pages, hosted on your server.

You can host any of these page types on your own server: Petition, Letter, Donation, Recurring Donation, Survey, Call, Signup, Event Creation, Event.

Pages are fully functional when moved to your site, even tricky features like Congress person lookups. Just as with pages hosted in ActionKit, your end users will be recognized, error messages returned if information is missing, and action and source data immediately written to the ActionKit database. You can include custom user and action fields in your offsite pages. For donation pages, you can even display the suggested ask amount based on the user's Highest Previous Contribution.

In fact, you can do almost anything in an offsite page that you can do by customizing your ActionKit templateset. To use the more advanced functionality, you can can customize templatesets as if you were hosting the page with ActionKit and the code we give you to embed in your site will include the custom features you've added. It's a good idea to read the templateset section above to get a sense of what's possible.

If you just want an easy way to insert a simple form in your site, your other option is to use the Ajax signup widget.

How

The steps for creating a page to be hosted offsite are as follows:

1 Create your page in ActionKit. Even though you're hosting the page somewhere else, ActionKit needs the information you enter when creating a page, particularly the Action basics and After-action info.

2 Make your selections on the Action basics screen just as you would for a hosted page, including selecting the fields you want the page to require.

3 Check Host outside ActionKit CMS on the Edit content screen. If you enter the page's URL, we'll link to it (so you can see it from the 'view' link on the dashboard and any end users who hit your ActionKit page will be redirected).

4 Select a templateset that includes the user form you want on the page. For example, if you want to include a custom user field, you could add the field to a templateset and select that set. Then it will be included in the user form you copy over to your page.

5 Optionally, you can enter the page content. If you don't, we'll fill the fields with placeholders.

6 Fill out the After-action info screen just as you would for a hosted page. By default, the Redirect URL will direct users to an ActionKit-hosted thank you page. If you use this option, be sure you've entered thank you content on the Edit Content screen. Alternatively, direct users to a thank you page you're hosting by entering the URL here.

7 On the final Preview/Get HTML screen, you can download the rendered page as well as view it in your browser.

On this screen you can choose:

  • Include wrapper - Leave checked to download the header and footer from the templateset you selected in step 2, along with the form. Uncheck to download just the the form. Including the wrapper is a good idea if you've got a design in ActionKit already that you want to use for your page because then you can just upload the HTML to your site.
  • Fix relative URLs - Leave checked and we'll change relative links in the page (like /samples/actionkit.js) to full links including your ActionKit domain.
  • Make URLs HTTPS (donation pages only) - If you leave this checked, we'll make all CSS and JavaScript references use HTTPS instead of plain HTTP to avoid security warnings. You'll need to make sure your wrapper uses HTTPS too, and that the sites you load resources from are set up for HTTPS.

8 Preview your page, then download your html. After you download the HTML for your page, you may want to download the HTML for your thank you page. You can also do this from the Preview/Get HTML screen.

9 You can copy the HTML you downloaded directly to your site, or you can cut and paste the relevant sections. If you're taking the latter approach, we suggest reviewing the section on Working with Templates. You don't need to copy the Django snippets (like {% load actionkit_tags %}) over, but you do need to make sure to copy over some things like the script tag to load actionkit.js.

Things you almost certainly want to include (which are described in the Working with Templates section):

  • <meta charset=UTF-8" />
  • //ajax.googleapis.com/ajax/libs/jquery/1.3.2/jquery.min.js
  • /resources/actionkit.js
  • To trigger our processing. you'll also want to have:
<script type="text/javascript">
  actionkit.forms.contextRoot = 'http://yourgroup.actionkit.com/context/';
  actionkit.forms.initPage();
  actionkit.forms.initForm('act')
</script>
  • actionkit.css
  • known user and unknown user divs
  • User form: We suggest cutting and pasting our user form over directly. Make sure you see the custom fields you added in there.

10 Set the other site's domain as a client domain if you'd like actions from mailings to be tracked as if this were an ActionKit hosted page.

11 Test!

  • View the page. Look right?
  • Send yourself a test mailing linking to the page; follow the link
  • Confirm you're recognized by the page if you should be
  • Submit and confirm you got to the right thanks page
  • Check data capture: the action, the source, user field values
  • Go back and load the page with no akid; try to skip a required field and confirm you get an error, check other validation as desired
  • Submit without an akid, make sure the action is recorded

Adding A Thermometer / Progress Meter To Your Page

You Are Loading And Using actionkit.js

If you're loading actionkit.js, e.g. to use the ActionKit user recognition and validation, you can probably simply copy the template progress_meter.html into your page. You can find the progress_meter.html template in the Original templateset:

The code in actionkit.js and progress_meter.html make a few assumptions about the context in which they run:

  • actionkit.js uses the presence of a hidden form value to know if it should load and display counts. progress_meter.html includes it, but this input must be inside the form.

<input type="hidden" name="want_progress" value="1" />

  • The page (identified by the hidden input named page in your form) will have to have a Goal and Goal type set in the ActionKit DB.
  • The progress meter won't show up until there is at least 1 action.
  • The progress_meter.html template is a mix of a Django template and a text/ak-template. You want to use the ak-template part, but not the Django part. (ak-templates are rendered by actionkit.js after loading data from the ActionKit server.)
  • The progress meter styles are in actionkit.css

You Want To Add Your Own Thermometer / Progress Meter

Using /progress/?page={{ page }}

You can get a count of actions on your page by making a request to /progress/?page={{ short name of your page }}. We'll return a JSONP callback. The default callback is named actionkit.forms.onProgressLoaded, but you can use the callback parameter to set the name to anything you want.

addToCount({
   "goal"     : null,
   "goal_type": "actions",
   "age"      : 0.0008280277252197266,
   "time"     : 1415367730.571025,
   "total"    : {"actions": 111},
   "recent"   : {"actions": 111}
})

The fields returned are:

  • total - dictionary with "actions" or "dollars" as a key and the result as value
  • goal - the goal set on the page.
  • goal_type - the goal_type set on the page. What to count:
    • actions (default) - total actions * SELECT count(*) as actions FROM core_action WHERE core_action.page_id = ?
    • dollars - sum of order totals * SELECT coalesce(sum(total), 0) as dollars FROM core_action JOIN core_order ON (core_action.id = core_order.action_id) WHERE core_order.status = 'completed' AND core_action.page_id = ?
  • age - how long ago this result was calculated
  • time - time the server calculated the result
  • recent - a dictionary like total, but with only actions or dollars from the 600 seconds before 'time'
  • form_name - if you include form_name in the request, we'll stick it here.

The default is to count actions. You can count dollars by setting the goal_type attribute of your page (in Action Basics on the compose page or via an API).

The totals are cached for 600 seconds. If you want the count to update more often you'll need to use the total and the age to calculate a rate and apply it to the cached value. Exercise for the reader! Before you worry too much about the caching, make sure you really have a use case where a single end-user (i.e. not the leadership of your organization) is going to watch the progress meter increase over time.

You can include multiple pages in your total by requesting a total for each page and adding them together. Here's an example of how you might approach adding multiple counts to the same thermometer using jQuery.

function setCounter(value) {
    $("#counter").html(value + ' actions taken!')
}

function combineThermometers(pages, onComplete, count) {
    var page;
    count = count || 0;

    if (pages.length) {
        page = pages.shift();
        jQuery.ajax('http://docs.actionkit.com/progress/?page=' + page,
            {
            dataType: 'jsonp',
            success: function(progress, text, xhr) {
                    combineThermometers(pages, onComplete, count + progress.total.actions)
            }
        });
    } else {
        onComplete(count);
    }
}
$(function() {
    combineThermometers(["schumer_reyes", "schumer", "conyers"], setCounter);
});
Using The RESTful API To Run A Query

If you have a server-side hosting environment that allows you to take advantage of the RESTful API, then you can write and run your own query for counting actions, users or anything else you want.

We recommend using a saved report, which will allow you to re-use the query for multiple pages (remember that you can pass parameter into reports).