ActionTag is an easy way to embed forms on any site. Much like Twitter Embedded Timelines, the idea is to use one line of JavaScript and one line of HTML to have a foolproof way to present a form that posts back to your NGP database. Please note that ActionTag does not work on IE9 or older browsers.

What is it?

ActionTag is our name for our embeddable forms functionality. Embeddable on any page on the web, it will:

• Make an API call to retrieve that form’s definition (aka which fields should display)
• Render a fully functional form to the screen
• Pre-fill that form under certain circumstances
• Handle submission of that form back to the NGP servers
• Deal with behaviors that occur after submission such as:
  • Displaying another form as configured NGP
  • Showing a thank you message as configured in NGP
  • Redirect to another URL, as defined in NGP

How to Find the Embed Code

The easiest way to use ActionTag on your own website is to use the embed codes provided inside the form builder. In Online Actions there is a “Link & Embed” button at the top of every step of the form builder, which is enabled once you have published your form. In EveryAction 7, you can find the embed code on the last step of the Online Page Manager (the step labeled “Published Page Info”).

Getting Started with Manually Embedding a Form

All that’s necessary to use ActionTag is to drop a special <div> tag on any page along with our JavaScript file. For example:

  <script type="text/javascript" src="https://d1aqhv4sn5kxtx.cloudfront.net/actiontag/at.js"></script>
  <div class="ngp-form" data-id="-9061805400222859264"></div>

We use the class ngp-form to indicate that this is the place where the form should render.

NOTE: any use of ActionTag for processing payment information must be embedded in a TLS-secured page.

To specify which form to render, add the only other required data attribute, the data-id attribute, e.g. data-id="-9061805400222859264". Each form published has a unique id which can be used in this tag. Please note: that some form IDs start with a minus sign (-), as shown in the example above. Do not delete this as it is a part of the form ID.

These are the simplest cases. Below are some more of the data attributes that can optionally be added to the tag to alter its behavior.

SmartLinks

For users who draft emails for use in Targeted Email, a special merge field is available which auto-fills user contact data merge fields in an ActionTag form. To use this merge field, append contactdata={{ContactData}} to any URL which hosts an ActionTag form, and embed the resulting URL in the body of a Targeted Email. Doing so will cause the following merge data to be automatically merged in to when email receipients click through the URL in the email, and view the form:

• First Name
• Middle Name
• Last name
• Subscriber Email
• Street Address
• City
• State or Province
• Zip or Postal
• Home Phone
• Cell Phone
• Work Phone
• Employer
• Occupation
• Prefix
• Suffix

Example

1. You create a form in Online Actions, and use ActionTag to embed it at https://www.peopleforgood.com/donate.
2. You draft an email to your supporters.
3. In the body of the email, you include the following URL: https://www.peopleforgood.com/donate?contactdata={{ContactData}}
4. You paste the body of the email into Targeted Email, and send the email to your supporters.
5. When Targeted Email generates the email, it prepares a special encoded string, specific to each supporter. This encoded string is merged in to the personalized email which each supporter receives. For example, supporter Jane Casey might receive an email with the URL https://www.peopleforgood.com/donate?contactdata=1234ABC.
6. Jane Casey, one of your supporters, receives the email and clicks the link.
7. ActionTag displays the form from step 1.
8. ActionTag reads the contactdata string, and merges Jane Casey’s data into the form display.

It is also possible to add contactdata alongside other parameters. For example, if you wanted to use the Targeted Email merge field for a record’s highest previous contribution to set the contribution amount on a form, defaulting to $3 if the record is a nondonor, then the url would look like this: https://www.peopleforgood.com/donate?am={{HighestPreviousContribution or '3'}}&contactData={{ContactData}}.

Using Query Strings

A query string is something you can add to the end of the URL your form lives at, e.g. www.someurl.com/formid?foo=bar Primarily, query string values are used to pre-fill values in the form. The general format is that the first bit is the name of the form field, followed by an equals sign and then whatever data you wish to pre-fill that form field with. ActionTag assumes US formats for all fields (phone, postal code, amounts, etc.).

The way to add these onto a form is that the first one needs to use a question mark, and other subsequent ones use an ampersand, e.g. www.someurl.com/formid?fn=John&ln=Adams

Available visible fields to be filled:

Name	Parameter	Sample	Notes
AddressLine1	add1	add1=1250+Hancock+St.
AddressLine2	add2	add2=Ste.+202
Additional Contribution Value	AdditionalContributionValue	AdditionalContributionValue=25	Prefill the additional contribution amount on event forms only
Amount	am	am=5
AmountOptions	amtOpts	amtOpts=3,5,20.16,50,100	This sets the radio button options on a contribution page, enabling dynamic ask amounts. To select a particular contribution amount, use Amount
City	ci	ci=Boston
Country	c	c=United+States
Date of Birth	dob	dob=12-31-1999
EmailAddress	em	em=john.adams@example.com
Employer	ep	ep=ACME Industries
Ethnicity	ethn	ethn=1,2,3	1 • Afghani 2 • Arab 3 • Asian Indian 4 • Bangladeshi 5 • Bhutanese 6 • Brazilian 7 • Chinese 8 • East African 9 • Filipino 10 • Haitian 11 • Hmong 12 • Indo Carribean 13 • Lao 14 • Nepali 15 • Pakistani 16 • Somali 17 • Sri Lankan 18 • Tibetan 19 • Vietnamese 20 • Latino 21 • Arabian 22 • Armenian 24 • East European 25 • Indian 26 • English (British) 27 • French 28 • German 29 • Hispanic (Spanish) 30 • Irish 31 • Italian 32 • Japanese 34 • Polish 35 • Native American 36 • Scottish 37 • Swedish 39 • Samoan 40 • Korean 42 • Tagalog (Filipino) 44 • Czechoslovakian 45 • Norwegian 46 • Dutch 47 • Greek 48 • Hungarian 49 • Middle Eastern 50 • Russian 51 • Ukrainian 52 • Welsh 54 • Bulgarian 55 • Burmese 56 • Cambodian 57 • Estonian 58 • Ethiopian 59 • Finnish 60 • Icelandic 61 • Indonesian 62 • Hebrew 64 • Latvian 65 • Lithuanian 66 • Malaysian 67 • Manx 68 • Portuguese 69 • Alaskan 71 • Swiss 72 • Thai 73 • Turkish 74 • Yugoslavian 75 • Danish 76 • African 77 • Hawaiian 78 • African American 81 • Asian 82 • Hispanic 83 • Mixed Ethnicity 85 • Other 86 • Persian 87 • Yemeni 88 • Egyptian 89 • Morrocan 90 • Lebanese 91 • Caucasian 92 • Jewish 93 • Chamorro 94 • Guamanian 95 • Mariana Islander 96 • Mien 97 • Bengali 98 • Chin 99 • Karen 101 • Mongolian 102 • Native Hawaiian/Pacific Islander 103 • Okinawan 104 • Singaporean 105 • Taiwanese 106 • Tongan 120 • Unknown
FacebookProfileUrl	fb	fb=http://www.facebook.com/JohnAdamsPresident
FirstName	fn	fn=John
Gender	gen	gen=1,2,3	1 • Androgynous 2 • Female 3 • Female to Male 4 • FTM 5 • Gender Fluid 6 • Gender Non-conforming 7 • Genderqueer 8 • Male 9 • Male to Female 10 • Man 11 • MTF 12 • Non-Binary 13 • Prefer Not to Say 14 • Questioning 15 • Trans 16 • Transgender 17 • Woman 18 • Agender 19 • Androgyne 20 • Bigender 21 • Butch 22 • Femme 23 • Gender Questioning 24 • Gender Variant 25 • Genderless 26 • Hijra 27 • Intersex 28 • Masc 29 • Neither 30 • Neutrois 31 • Non-Op 32 • Other 33 • Pangender 34 • Polygender 35 • Queer 36 • Transfeminine 37 • Transgender Female 38 • Transgender Male 39 • Transgender Man 40 • Transgender Person 41 • Transgender Woman 42 • Transmasculine 43 • Transsexual 44 • Transsexual Female 45 • Transsexual Male 46 • Transsexual Man 47 • Transsexual Person 48 • Transsexual Woman 49 • Two Spirit
HomePhone	hp	hp=6175551234
IsRecurring	r	r=true
LastName	ln	ln=Adams
MiddleName	mn	mn=Quincy
MobilePhone	mp	mp=6175551234
Occupation	oc	oc=President
PostalCode	pc	pc=02144
Preferred Languages	preflang	preflang=2	1 • Bengali 2 • Cantonese 3 • English 4 • French 5 • Gujarati 6 • Hindi 7 • Japanese 8 • Korean 9 • Malayalam 10 • Mandarin 11 • Nepali 12 • Punjabi 13 • Russian 14 • Sinhalese 15 • Spanish 16 • Tagalog 17 • Tamil 18 • Tibetan 19 • Urdu 20 • Vietnamese 21 • Arabian 22 • Armenian 23 • Misc Asian 24 • Misc European 25 • Indian 26 • German 27 • Hispanic (Spanish) 28 • Italian 29 • Pakistani 30 • Polish 31 • Swedish 32 • Samoan 33 • Tagalog (Filipino) 34 • Chinese 35 • Czechoslovakian 36 • Norwegian 37 • Dutch 38 • Greek 39 • Hungarian 40 • Middle Eastern 41 • Bangladesh 42 • Bulgarian 43 • Burmese 44 • Cambodian 45 • Estonian 46 • Ethiopian 47 • Finnish 48 • Icelandic 49 • Indonesian 50 • Hebrew 51 • Lao 52 • Latvian 53 • Lithuanian 54 • Malaysian 55 • Portuguese 56 • Sri Lanka 57 • Thai 58 • Turkish 59 • Yugoslavian 60 • Danish 61 • African 62 • Amharic 63 • Arabic 64 • Croatian 65 • Somali 66 • Tigrinya 67 • Hmong 68 • Bosnian 69 • Creole 70 • Serbian 71 • Ukranian 72 • Bhutanese 73 • Chamorro 74 • Ilocano 75 • Karenni 76 • Malayo 77 • Mien 78 • Swahili 79 • Tokelauan 80 • Kannada 81 • Marathi
Prefix	p	p=Mr
Pronoun	pro	pro=1	1 • She/Her/Hers 2 • He/Him/His 3 • They/Them/Theirs 4 • Xe/Xem/Xyrs 5 • (F)ae/(F)aer/(F)aers 6 • E/Em/Eirs 7 • Ey/Em/Eirs 8 • Per/Per/Pers 9 • Sie/Sie/Hirs 10 • Tey/Ter/Ters 11 • Ve/Ver/Vers 12 • Ve/Ver/Vis 13 • Ze/Hir/Hirs 14 • Zie/Zim/Zis
Race	race	race=1	1 • Asian 2 • Black or African American 3 • Caucasian or White 4 • Native American 5 • Native Hawaiian 6 • Other 7 • Pacific Islander 10 • Hispanic 11 • Jewish 12 • Middle Eastern
SexualOrientation	sexorient	sexorient=1,2,3	3 • Asexual 5 • Bisexual 6 • Demisexual 21 • Gay 9 • Heterosexual 22 • Lesbian 19 • Other 14 • Pansexual/Omnisexual 18 • Prefer not to Say 16 • Queer
SpouseName	sn	sn=Abigail+Adams
StateProvince	st	st=MA
Suffix	s	s=Esq.
TwitterHandle	tw	tw=the_real_adams
WorkAddressLine1	w1	w1=1600+Pennsylvania+Ave
WorkAddressLine2	w2	w2=Oval+Office
WorkCity	wc	wc=Washington
WorkEmail	we	we=john.adams@example.com
WorkPhone	wp	wp=2025551234
WorkPostalCode	wz	wz=20500
WorkStateProvince	ws	ws=DC
Yes Sign Me Up For Updates	ae	ae=1 or ae=true ae=0 or ae=false

Elements that are specific to Events List Pages (these fields are visible on the ActionTag form):

Name	Parameter	Sample	Notes
Display Results	results	results=true
Distance in Miles	radius	radius=50
Date From	date_start	date_start=06-26-2018
Date To	date_end	date_end=06-26-2018
Event Type	event_type	event_type=285730,294375
Sort	sort	sort=2	1 • Date 2 • Distance

Elements that are specific to Events Signup Pages (these fields are visible on the ActionTag form):

Name	Parameter	Sample	Notes
Location	location	location=1816
Role	role	role=250634
Shifts	shifts	shifts=11631||11632

Elements that are specific to Contribution forms with Tribute & Gift Memberships functionality enabled (these fields are visible on the ActionTag form):

Name	Parameter	Sample	Notes
Enable Tribute Gift	t	t=true
Honoree Name	honoree	honoree=Barack+Obama
In Honor or in Memory of	ttype	ttype=1 “In memory of” ttype=2 “In honor of”
Notification Send Copy	recipient_em_copy	recipient_em_copy=1 or recipient_em_copy=true recipient_em_copy=0 or recipient_em_copy=false	Affects checkbox used to indicate whether or not to send a copy of a notification to the donor.
Include Recipient (Gift Memberships)	tn	tn=true	Used for Gift Memberships. Displays contact details for recipient.
Notify Recipient (Tribute Gifts)	tn	tn=true	Used for Tribute Gifts. Displays all recipient details.
Recipient Information
Recipient FirstName	recipient_fn	recipient_fn=John
Recipient LastName	recipient_ln	recipient_ln=Adams
Recipient Address Line 1	recipient_add1	recipient_add1=1250+Hancock+St.
Recipient City	recipient_ci	recipient_ci=Boston
Recipient State Province	recipient_st	recipient_st=MA
Recipient Postal Code	recipient_pc	recipient_pc=02144
Recipient Country	recipient_c	recipient_c=United+States
Recipient Email Address	recipient_em	recipient_em=john.adams@example.com

Elements that are specific to Premiums functionality enabled:

Name	Parameter	Sample
Shipping FirstName	shipping_fn	shipping_fn=John
Shipping LastName	shipping_ln	shipping_ln=Adams
Shipping Address Line 1	shipping_add1	shipping_add1=1250+Hancock+St.
Shipping City	shipping_ci	shipping_ci=Boston
Shipping State Province	shipping_st	shipping_st=MA
Shipping Postal Code	shipping_pc	shipping_pc=02144
Shipping Country	shipping_c	shipping_c=United+States

There are also elements that may not be visible, but have to do with how the form submission data is entered into the database:

Name	Parameter	Sample	Notes
Attributed Contact ID	attr	attr=VN96C3TBX36	Allows you to set which contact to attribute a contribution to. This value can be a VANID for forms created in Online Actions, or an NGP ID for forms created in EveryAction 7. (Used for Contribution forms only.)
Host Committee	ac	ac=VN96C3TBX36	Select host committee contact from a list of contacts in a dropdown. This value can be a VANID for forms created in Online Actions, or an NGP ID for forms created in EveryAction 7. (Used for Ticketed Events only.)
Kiosk Mode	kiosk	kiosk=true	Using this query string parameter disables FastAction and ActionProfile integration. This is useful if the user is using a form on a tablet or laptop in a public place and do not want the submission information remembered on that device. Notably, if you configure one form to redirect to another form (what we refer to as secondary ask), the form fields on the second fom will not be pre-populated by the submission info from the first form. If you are launching the form with knowledge of who a contact is, kiosk mode does still allow you to prefill form fields using other query string values, e.g. fn=Michelle as documented above.
MarketSource	ms	ms=201409_fb_birthday_v1	Can be used to track different ad buys to the same form to compare ROI
SourceCodeId	sourceid	sourceid=57	Either adds or overrides the defined source code on the form. This only applies to contribution forms. You must use the source code ID, not the source code name.
QuickSign	quick	quick=true	Automatically submits the form and segues to the next action (thanks page, secondary ask, or an arbitrary other URL) if all the required fields are prefilled by either a query string value or ActionProfiles. This does not work for contribution or event forms.
Best Ask	ss	ss=true	Enables our Best Ask feature for adjusting your suggested contribution amounts.
Social Network Referral	snw	snw=1 Facebook snw=2 Twitter	Indicates whether the user was referred to the form from Facebook or Twitter.

Using Google Remarketing Codes

Forms with the new NGP are rendered by the client’s browser, and in order to use Google remarketing codes, you have to reconstruct them to load AFTER the form has loaded.

Here’s an example of what Google will give you as a remarketing code:

<!-- Remarketing tags may not be associated with personally identifiable information or placed on pages related to sensitive categories. For instructions on adding this tag and more information on the above requirements, read the setup guide: google.com/ads/remarketingsetup -->
<script type = "text/javascript">
    /*  <![CDATA[ */
    var google_conversion_id = 985021774; <!-- this will vary by client -->
var google_conversion_label = "lXkMCIq98gYQzvrY1QM"; <!-- this will vary by client -->
var google_custom_params = window.google_tag_params;
var google_remarketing_only = true;
/* ]]> */
</script>
<script type="text/javascript" src="https://www.googleadservices.com/pagead/conversion.js">
</script>
<noscript>
  <div style="display:inline;">
    <img height="1" width="1" style="border-style:none;" alt=""
      src="https://googleads.g.doubleclick.net/pagead/viewthroughconversion/985021774/?value=0&label=lXkMCIq98gYQzvrY1QM&guid=ON&script=0" />
  </div>
</noscript>

Notice that the conversion ID and conversion labels are in two places. First in the regular javascript and second inside the <noscript> code block. These are the values you need to copy into the new code snippet.

Here’s the new code you need to use, make sure to grab the conversion ID and label from the code Google provided, and insert them below. Once you’ve updated this snippet with your account information, you can copy it and paste it into the source of the NGP form page by clicking the “source” button and paste.

<script type="text/javascript">
    var img = document.createElement("img");
    var trackUrl = "https://googleads.g.doubleclick.net/pagead/viewthroughconversion/985021774/?value=0&label=lXkMCIq98gYQzvrY1QM&guid=ON&script=0"; <!-- change ID (985021774) and label (lXkMCIq98gYQzvrY1QM) in this line -->
    img.src = trackUrl;
    document.body.appendChild(img);
</script>
<noscript>
    <div style="display:inline;">
        <img height="1" width="1" style="border-style:none;" alt=""
          src="https://googleads.g.doubleclick.net/pagead/viewthroughconversion/985021774/?value=0&label=lXkMCIq98gYQzvrY1QM&guid=ON&script=0" />
        <!-- change ID (985021774) and label (lXkMCIq98gYQzvrY1QM) in this line -->
    </div>
</noscript>

Data attributes on the ActionTag div are the way to pass certain data or instructions to ActionTag to influence its behavior.

Since these attributes are part of the div, any CMS or website system can easily write code that will consume ActionTag with the characteristics they desire. This is the way we have written our own Drupal modules in-house.

What follows are the data attributes we currently support:

data-id (required)

It is used to specify the id of the form to render. Only required if data-form-url is not used. Note that an advocacy-related form must use the data-form-url attribute instead. Example, to load a non-advocacy-related form with id 12345:

<div class="ngp-form" data-id="12345"></div>

data-form-url (required)

It is used to specify the url from which the form definition is retrieved. Only required if data-id is not used, or if presenting an advocacy related form, which requires getting the form definition from a different endpoint. Example, to load a form from a url:

<div class="ngp-form" data-form-url="https://api.myngp.com/v2/forms/12345"></div>

For advocacy related forms, you have to request the form definition through our advocacy service, which we creatively call advocator. This url is constructed using the following pattern:

• Advocacy form proxy url, e.g. https://advocator.ngpvan.com
• The URL encoded database API endpoint, meaning take the endpoint https://api.myngp.com/v2/forms/ and represent it like this: https%3A%2F%2Fapi.myngp.com%2F%2Fv2%2FForms%2F
• the form ID, e.g. 12345
• and finally the string ngpForm at the end

Complete example for an advocacy related form, where we grab the form definition from the advocacy endpoint, with the rest of the form ID URL encoded after:

<div class="ngp-form" data-form-url="https://advocator.ngpvan.com/https%3A%2F%2Fapi.myngp.com%2F%2Fv2%2FForms%2F12345/ngpForm"></div>
``

data-databag

(optional) - Used to specify whether to use NGP VAN ActionProfiles to fill the form fields. In order for this functionality to work, the site using this must be white-listed by NGP VAN. Contact support if you are interested in getting your URLs whitelisted.

Note: databag is the legacy name for ActionProfile, hence the attribute/name mismatch.

• Default: nobody
• Options:
  • nobody - disable this functionality
  • everybody - Allow pre-filling of information from any site in the NGP VAN network. Also requires sharing pre-fill data with other sites in the NGP VAN network.

Example, to enable the NGP VAN Profile filling (assuming the site on which this tag is sitting has been white-listed):

 <div class="ngp-form" data-id="12345" data-databag="everybody"></div>

data-endpoint

(optional)- Used to specify a non-default API endpoint for retrieving the form definition and submitting the resulting data. This is used mostly for hitting development servers; though, if your NGP instance is accessed by a URL other than www2.myngp.com, you likely need to use this attribute.

• Default: https://api.myngp.com

Example, to load the definition and submit to http://developerboxname.local

<div class="ngp-form" data-id="12345" data-endpoint="http://developerboxname.local"></div>

data-formdef-endpoint

(optional) - This attribute defines a different read endpoint from the POST endpoint defined above. Primarily this is used to call the form definitions from Amazon S3, which NGP will automatically update on every form publish. This leads to faster load times for your forms, especially in peak usage situations, so it is recommended for use in every ActionTag implementation.

• Default: value of data-endpoint attribute.

Example, to read the form definition from Amazon S3 instead of the NGP API servers:

<div class="ngp-form" data-id="12345" data-formdef-endpoint="https://formdefs.s3.amazonaws.com/api.myngp.com"></div>

data-labels

(optional)- Used to specify the placement of the labels when the form is rendered.

• Default: above
• Options:
  • inline - available only for the signup form type, it sets the labels as the HTML5 placeholder attribute on the input.
  • above - displays form labels above the form fields with a tag

Note, the rationale here is that, while labels being above or beside the input can be altered with CSS, making them appear as placeholders is more complicated.

Example, to have labels appear as placeholders:

<div class="ngp-form" data-id="12345" data-labels="inline"></div>

data-resource-path

(optional) - Used to specify location of ActionTag resources such as actiontag.min.css. Primarily used for internal development purposes.

• Default: https://d1aqhv4sn5kxtx.cloudfront.net

Example, to use /sites/xyz/libraries/actiontag:

<div class="ngp-form" data-id="12345" data-resource-path="/sites/xyz/libraries/actiontag"></div>

data-template

(optional) - This attribute allows you to indicate which template to use. Note: we may deprecate this functionality in the future and consolidate down to just one template.

• Default: minimal
• Options:
  • minimal - Minimal form template
  • accelerator - Template used by our Accelerator websites
  • oberon - legacy template for the act.myngp.com theming, and most likely to get deprecated

Example, to load the minimal template set:

<div class="ngp-form" data-id="12345" data-template="minimal"></div>

Overview & Intended Audience

Callbacks are a rather technical feature set, and are not needed for the vast majority of uses of ActionTag. The callbacks described below are powerful, but also probably require some experience doing web development, and are not needed for most uses of ActionTag. Feel free to skip the rest of these docs unless you are a developer.

We have a series of callbacks in ActionTag which allow developers to alter bits of functionality. In order for ActionTag to know about your callback, we have a simple registration process.

First create the global JavaScript variable nvtag_callbacks (but only if it doesn’t already exist). The following snippet accomplishes this:

var nvtag_callbacks = nvtag_callbacks || {};

If your code is within a closure, you will need to explicitly ensure it is declared in the global namespace so ActionTag can find and reference it. Here that’s done with a local reference so that we no longer have to reference it by calling window.nvtag_callbacks:

window.nvtag_callbacks = window.nvtag_callbacks || {};
var nvtag_callbacks = window.nvtag_callbacks;

The last bit is callback specific. Perhaps you want to add a postRender callback to do something after the ActionTag form has been rendered.

1. Instantiate that callback as an array if it doesn’t yet exist
2. Create the actual callback function. The arguments to your function are the callback arguments listed below
   • Note, the first argument to a callback is always the name of that callback. This is done in an attempt to allow one function to be registered from multiple callbacks and then allow that function to handle things internally.

3. Push your callback onto the postRender callback array

   nvtag_callbacks.postRender = nvtag_callbacks.postRender || [];
   // This function can be called anything, we don't care
   var sampleCallback = function() {
    alert("The form has been rendered!");
   }
   nvtag_callbacks.postRender.push(sampleCallback);
   

   Now your callback code will be called by the ActionTag at the time that postRender should happen! (which is after rendering of the form is complete).

Putting it all together:

var sampleCallback = function() {
  alert("The form has been rendered!");
}
var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.postRender = nvtag_callbacks.postRender || [];
nvtag_callbacks.postRender.push(sampleCallback);

At the right time in the ActionTag process, we will iterate over each of the callbacks in that array and call them.

Technical background

We use our callbacks syntax to put it into the global namespace because ActionTag loads asynchronously. Also, we wish to support multiple callback sources, hence the instructions to not redeclare it over and over again.

A warning on the power of these abilities

Since our callbacks allow you to alter internals of our system, it is possible to make quite a mess of things, sometimes even in potentially dangerous/breaking ways. With great power comes great responsibility. For example, using the alterFormDefinition() callback:

var alterFormDefinition = function(args) {
  // This will blank out the form_elements array thereby effectively
  // breaking this form definition!
  args.form_definition.form_elements = [];
  return args;
};

So always test your callbacks carefully on a page before putting them live.

A note on the examples below

For the examples given below with each callback we are omitting the following bit:

var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.postRender = nvtag_callbacks.postRender || [];
nvtag_callbacks.postRender.push(sampleCallback);

Note that this must happen for each callback in order for them to be registered and called by ActionTag.

alterErrors

alterErrors (args)

args is a dictionary with the following keys:

• val - The current value of this field
• field_name - The name of this field
• require_valid - Errors, if any.
• def - This element’s definition.

This callback is called when checking the error state of a field. It allows you to intercept the error and alter it.

An error should take one of the 2 following states:

• false - There is no error
• string - Text description of error

alterErrors example

alterFill

alterFill(args)

args is a dictionary with the following keys:

• fill_dict - The fill dictionary. Key/value pairs.
• fill_source - None, BrowserDatabag, PreviousFormState, RecipientDatabag, or QueryString.

This callback is called after the form has completed rendering but before it is filled allowing you to intercept and alter the values which are pre-filled on the form.

Note: In order for this callback to work properly, you must return the args dictionary with your modified form_definition.

alterFormDefinition

alterFormDefinition(args)

args is a dictionary with the following keys:

• form_definition - The form’s definition, which we define as the JSON blob that composes what the form should look like.

This callback is called anytime the application requests the form definition. This is used throughout the system, both for rendering and for many other mechanics.

Note: In order for this callback to work properly, you must return the args dictionary with your modified form_definition.

Example usage

alterPost

alterPost(args)

args is a dictionary with the following keys:

• data - The form state / user data.
• url - The URL to which the data will be posted.
• form_id - The public ID of the form.
• form_definition - The form definition.

This callback is called before POSTing data. It is used to alter the data that will be POSTed.

Note that only fields which already exist on the form may be modified during alterPost. It is not possible to add new fields to the form submission in this callback.

alterRequireValid

alterRequireValid(args)

args is a dictionary with the following keys:

• val - The current value of this field
• field_name - The name of this field
• require_valid - boolean, true if required, false if not.
• form_def - The form definition.

This callback is called when determining if a field is required for the form to validate.

onSubmit

onSubmit(args)

This callback is called when a form is submitted.

args is an empty dictionary.

postFill

postFill(args)

args is a dictionary with the following keys:

• view - The ActionTag form view
• fill_dict - The fill dictionary. Key/value pairs.
• submit - The function responsible for submitting the form.

This callback is called after the form is filled.

postRender

postRender(args)

args is a dictionary with the following keys:

• form_definition: The form definition.
• options: The view’s options.
• thank: boolean, true if this is a thank you message, false if it is not.

This callback is called after the form has completed rendering but before it is filled. Common use cases are to fire JavaScript behaviors that require the form to be present.

var myPostRender = function(args) {
  alert("The form has now been rendered!");
  return args;
};

Note, multiple things induce the rendering of a form so this will likely be called multiple times. Ensure any code that depends on postRender() is tolerant of that.

Optionally receive the view and alter any options or override any methods on it:

var myPostRender = function(args) {
    console.log(args.form_definition);
    return args;
}

preSegue

preSegue(args)

This hook is called after a successful form submission, but prior to the segue to the next thing.

As a quick primer, there are, at current, 3 different things which can happen after a successful form submission:

• Display a thank you message
• Display another form (aka Secondary ask)
• Redirect to another page anywhere on the internet

preSegue() happens before the transition to this next step so it’s useful for intercepting it and altering the behavior based on the submitted values and/or the response from the server.

It receives two arguments:

• submitted_values - The values which were submitted across the network
• response - The response from the server to that submission

segue

segue(args)

This hook is called when a segue is happening.

As a quick primer, there are, at current, 3 different things which can happen after a successful form submission:

• Display a thank you message
• Display another form (aka Secondary ask)
• Redirect to another page anywhere on the internet

We call the transition from one thing to another thing a segue. This callback is called when making that transition.

Note, it is NOT called in case 3 above because we have no control over another page on the internet.

It receives three arguments:

• formviews - The form views in question
• thank - boolean, true if this is a thank you message, false if it is not.
• calling_tag - The view in question.

  {
    event: 'FormEvent',
    eventCategory: 'ContributionForm',
    eventAction: 'Form Load',
    eventLabel: 'Minimal',
    eventValue: 12,
    eventActivistCodes: ['3456','8901'],
    eventSourceCodeId: 2345
  }

dataLayer = [{

  /* Triggering Event */
  'event': 'transaction',

  'ecommerce': {
    'purchase': {
      'actionField': {
        /* Online Ref # (can be used to search for transaction) */
        'id': '25970195',

        /* Denoting a Transaction from ActionTag */
        'affiliation': 'NGPVAN',

        /* Total Transaction Revenue */
        'revenue': '2600.00'
      },

      'products': [
        {
        /**
         * ID based upon unique session ID, combined with the
         * individual product transaction.
         * This value does not remain staticly assigned to the item for 
         * future purchases or for purchases by other users;
         * it is unique to the session)
         */
          'id': 'People for Good_4_713_2600.00',

          /* Unit Price (Contribution Amount) */
          'price': '2600.00',

          /* Organization Name */
          'brand': 'People for Good',

          /* Form Type */
          'category': 'ContributionForm',

          /* Count of Items */
          'quantity': 1,

          /* Selected Product */
          'name': 'People for Good_4_713_2600.00'
        }
      ]
    }
  }]
}];

dataLayer = [{

  /* Triggering Event */
  'event': 'transaction',

  'ecommerce': {
    'purchase': {
      'actionField': {
        /* Online Ref # (can be used to search for transaction) */
        'id': '25970195',

        /* Denoting a Transaction from ActionTag */
        'affiliation': 'NGPVAN',

        /* Total Transaction Revenue */
        'revenue': '200.00'
      },

      'products': [
        {
        /**
         * ID based upon unique session ID, combined with the
         * individual product transaction.
         * This value does not remain staticly assigned to the item for 
         * future purchases or for purchases by other users;
         * it is unique to the session)
         */
          'id': 'People for Good_4_713_40.00',

          /* Unit Price  */
          'price': '40.00',

          /* Organization Name as it Appears */
          'brand': 'People for Good',

          /* Form Type */
          'category': 'EventForm',

          /* Number of Tickets of this Type Purchased */
          'quantity': 1,

          /* Selected Value or Ticket Name */
          'name': 'Gala Silver Ticket'
        },
        {
            'id': 'People for Good_4_713_80.00',

            /* Unit Price */
            'price': '80.00',

            /* Organization Name as it Appears */
            'brand': 'People for Good',

            /* Form Type */
            'category': 'EventForm',

            /* Number of Tickets of this Type Purchased */
            'quantity': 2,

            /* Selected Value or Ticket Name */
            'name': 'Gala Gold Ticket'
        }
        ]
      }
    }]
  }];

alterErrors

Take the provided error message and adjust it to something else.

Example:

var myAlterErrors = function(args) {
      if (args.field_name === 'FirstName') {
        if (args.errors) {
          args.errors = "YOU MUST GIVE US YOUR FIRST NAME TO PROCEED";
        } else {
          if (args.val !== "Frank") {
            args.errors = "We only accept a first name of Frank";
          }
        }
      }
      return args;
};

var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.alterErrors = nvtag_callbacks.alterErrors || [];
nvtag_callbacks.alterErrors.push(myAlterErrors);

alterFormDefinition

Simple

A simple use case is to override some attribute of the definition:

// Implementation of an alterFormDefinition Callback
var alterFormTitle = function(args) {
  // Note, changing this title will not make a visual change unless the title is
  // used in the template which it's not by default in ActionTag.
  args.form_definition.title = "This title has been overridden";
  $('.status').html("<pre>Form Title: " + args.form_definition.title + "</pre>");

  // Must return the altered object so it will be used
  return args;
};

Intermediate

A bit more complex example is to alter something within the form definition. Let’s say you want to change the contents of the Header HTML markup. Note, in this example we are using the Underscore module to iterate over the elements

var changeHeaderHtml = function(args) {
  // args is a dictionary with a key of "form_definition"

  // iterate over each element, 
  _.each(args.form_definition.form_elements, function(child, index) {
      if (child.name === 'HeaderHtml') {
          child.markup = "<p>Replaced Markup</p>";
      }
  });

  return args;
};

Advanced: adding a field

Let’s say you want to add a field to the form definition to be collected:

var addSpouseField = function(args) {
  _.each(args.form_definition.form_elements, function(child) {
      if (child.name === 'ContactInformation') {
          spouse_field = {
              name: 'Spouse',
              title: "What is your spouse's name?",
              type: 'textfield',
              weight: 99, // We want it to appear at the bottom of the fieldset
              queryString: 'sp'
          };
          child.children.push(spouse_field);
      }
  });
  return args;
};

Note, for this case, if Spouse is not in the original form definition, the API would not be able to parse it, so you will need to intercept and store that POST value somewhere else.

Also note that since the added definition has a queryString of 'sp', it will fill if the page has a query string argument like: ?sp=Joe

Rearrange fields

Let’s say we want to rearrange some fields. Or perhaps we want to move some fields into another fieldset. The following example covers that case:

var rearrangeFields = function(args) {
  // First add a new fieldset to hold these fields
  var name_fieldset = {
      name: 'Name',
      title: 'Name',
      type: 'fieldset',
      children: []
  };
  var name_index = args.form_definition.form_elements.push(name_fieldset);
  // Decrement as push returns the length, we want reference to the last element
  name_index--;

  _.each(args.form_definition.form_elements, function(child) {
    if (child.name === 'ContactInformation') {
        _.each(child.children, function(element, key, children) {
            if (element.name === 'FirstName' || element.name === 'LastName') {
                // Add to our new name fieldset
                args.form_definition.form_elements[name_index].children.push(element);

                // Remove from the other fieldset
                children[key] = { 'type': 'hidden'};
            }
        });
        child.title = 'Address';
    }
  });
  return args;
};

In this case we are creating a new fieldset for Name, moving the name fields into that fieldset, removing them from their original fieldset (ContactInformation), and changing the title of the Contact Information fieldset to Address to better indicate its purpose.

Redirect based on recurring or contribution amount values

Perhaps you want to change where a donor goes after form submission in case they choose to give over a certain threshold or choose to give a recurring contributon. Using the preSegue callback you can look at the submitted values and make conditional redirects based on that information. Note, in practice you probably only want to use one of these two conditionals, but both are shown in the same example below for expediency:

var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.preSegue = nvtag_callbacks.preSegue || [];
nvtag_callbacks.preSegue.push(function submitSegue(args) {
  var contribAmount = parseFloat(args.postVals.Amount);
  var isRecurring = args.postVals.IsRecurring;
  if (isRecurring) {
      window.location = "http://www.yourdomain.org/recurring-thanks-page";
  }
  if (contribAmount > 5000) {
      window.location = "http://www.yourdomain.org/big-spender-thanks-page";
  }
  return args;
});

Obviously, you will want to adjust the threshold for high (or low) dollar conditional redirects, as well as the redirection destination in the above examples.

preSegue

Perhaps you want to track the contribution amount in another analytics package. Here’s how you capture it on form submission:

var contribAmount;
var submitSegue = function (args) {
    contribAmount = args.postVals.Amount;
    console.log(contribAmount);
    return args;
}
var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.preSegue = nvtag_callbacks.preSegue || [];
nvtag_callbacks.preSegue.push(submitSegue);

You could then call the variable contribAmount to pass off to your analytics service.

Alter country list

If you want to alter the list of countries on your forms, the following example shows you how to remove a country, rename a country, or potentially insert a new option, all using the postRender callback. Note: if adding a new country, make sure you map it back to an existing value so the address is entered to the system in a way we can process

var alterCountries = function(args) {
  // Remove a country by the value in the dropdown
   var removalItem = document.querySelector('select[name=Country] option[value="XK"]');
   removalItem.parentNode.removeChild(removalItem);

  // Rename a country publicly (but will map to the existing value in the database)
  var renamedItem = document.querySelector('select[name=Country] option[value="VI"]');
  // desired new text to display
  renamedItem.innerText = 'US Virgin Islands';

  // Insert a new country (not recommended, only use it to map a new entry to an existing value)
  // replace "Dominican Republic" with the name of country that comes right before the country you wish to add
  var previousCountry = document.querySelector('select[name=Country] option[value="EE"]'); 
  previousCountry.insertAdjacentHTML('afterend','<option value="Essos">Essos</option>');
}
var nvtag_callbacks = nvtag_callbacks || {};
nvtag_callbacks.postRender = nvtag_callbacks.postRender || [];
nvtag_callbacks.postRender.push(alterCountries);