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;


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 ( === '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 ( === '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'
  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