Forms with WordPress: Gravity Forms

Overview

When integrating an Act-On Form external post with WordPress, Gravity Forms is a popular and easy-to-use WordPress plug-in for generating forms. It has a number of options and there are numerous possibilities for you to send data to Act-On. However, the following are the integration methods we recommend. All of these methods will properly update the cookie Act-On places on your visitors' browsers.

See Integrating an Act-On Form External Post with WordPress for other WordPress form plug-ins.

There are slightly different steps to follow, depending on whether you would like Gravity Forms to redirect to a new page upon form submission or if you are using a 'Thank You' message for your form (displayed on the same page as your form). The option you choose depends on where you would like to send your website visitors once they submit a form, and the corresponding steps described below are all equally reliable.

For either of the above options, we will be working with the Confirmations section of the Gravity Forms interface. To navigate here:

1. Log into your WordPress administrator page.
2. Click Forms in the sidebar to load the Gravity Forms setup interface.
3. Click the name of the Form that you would like to integrate with Act-On.
4. Click Form Settings.
5. Click Confirmations.
6. Click Edit on Default Confirmation.

In this guide, you will see the following options for Confirmation Type listed below:

• Text
• Page
• Redirect

Choose the option that best fits how you would like to process your Gravity Forms submission. This process is done on a per-form basis within the individual forms' settings and does not apply globally to all your Gravity Forms.

Web developers: If you are comfortable modifying the WordPress functions.php file and doing a more advanced integration, you may want to see the Gravity Forms API-based integration section instead.

Standard Implementation: Text Method

Text will display a message when the form is submitted (your form will disappear on the page, and the message will appear in its place), but will not redirect the form submitter to a new page. If you are using this option:
 
Step 1:

In Act-On, navigate to Content > Forms, and create a form with the fields you are hoping to capture and store in a list. Your website visitors will not see this form - it exists as a 'proxy' used to receive data from Gravity Forms. Make note of the Data Field Name for each of your fields, as we will be feeding those Data Field Names into your Gravity Form.
 
Step 2:

In Act-On, navigate to Content > Form Post URLs. Generate an external post URL for the 'proxy form' you created in Step 1.
 
Step 3:

In the WordPress administrator interface, open up Gravity Forms and navigate to the Text confirmation behavior (steps to navigate there are described at the beginning of this article).

Step 4: 

Paste in the following script:

<script>var externalPostURL="FORM-POST-URL-GOES-HERE";var queryString="QUERY-STRING-HERE";var aoIfrm=document.createElement("iframe");document.body.appendChild(aoIfrm);aoIfrm.setAttribute("id","ifrm");aoIfrm.style.backgroundColor="transparent";aoIfrm.style.border="none";aoIfrm.style.width="1px";aoIfrm.style.height="1px";aoIfrm.src=externalPostURL+"?"+queryString</script>

• If you have any existing message present in this text box, paste the script below everything else.
• Note that the above script does not contain any line breaks (the new lines you see above is your browser using word-wrap). When you paste this, ensure that no hard line breaks are present as it breaks the Gravity Forms script implementation.
• Replace 'FORM-POST-URL-GOES-HERE' with the 'Form Post URL' you generated in Step 1, keeping the quotes.
• Replace 'QUERY-STRING-HERE' with your query string. 
  To create the query string, click the drop-down icon next to the text box, and you will see a list of fields available to your Gravity Form. Then, click the field name in this list for each field you would like to add. For example, this will add something like the following for the default First Name field:
  

  {Name (First):1.3}

• • With the above, this will pass the value of the submission. If I submit 'John', it will output 'John'. However, we also need to specify which input field this corresponds to. To do this, type in the name followed by an equals sign. The name you choose should match the corresponding data field in your Act-On proxy form.
  • If the name in Act-On has a space, you'll need to encode it. For example, a space (' ') is encoded as '%20' since we can't put a space in a URL.
  • An example that maps the value to 'First Name' (note the '%20' encoded space):
    

    First%20Name={Name (First):1.3}

  • This will output 'First%20Name=John' in our example mentioned above.
  • Do the same for your other fields, but separate them with a '&'. For example, here is what capturing first/last name and email could look like (note the ampersand characters):
     

    First%20Name={Name (First):1.3}&Last%20Name={Name (Last):1.6}&E-mail%20Address={Email:2}

Step 5:

Save your changes & then implement the form on a page by inserting the Gravity Form:

Important: Do not use AJAX as this can cause multiple form submissions.

Your form submitters will now have their information sent to Act-On and they will be converted to known visitors. If you see in Act-On that you are getting blanks for some of your form fields, double-check your mapping between 'Data Field Name' and the query strings you set in Step 4.

Standard Implementation: Page Method

Page sends the form submitter to an existing page that is part of your WordPress. If you are using this option:
 
Step 1:

In Act-On, navigate to Content > Forms, and create a form with the fields you would like to capture and store in a list. Your website visitors will not see this form - it exists as a proxy used to receive data from Gravity Forms. Make note of the Data Field Name for each of your fields, as we will be feeding those Data Field Names into your Gravity Form.
 
Step 2:

In Act-On, navigate to Content > Form Post URLs. Generate an external post URL for the proxy form you created in Step 1.
 
Step 3: 

In the WordPress administrator interface, open up Gravity Forms and navigate to the Page confirmation behavior (steps to navigate there are described at the beginning of this article).

• Select the page on your WordPress site that you would like your form submitters to be sent to.
• Check Pass Field Data Via Query String. This will expose a text area with a drop-down icon floating to the right of the text area.
• Click this icon, and you will see a list of fields available for your Gravity Form.
• Click the field name in this list for each field you want to add. For example, if you were to choose First Name it will add something like the following for the default First Name field:
  

  {Name (First):1.3} 

• With the above, this will pass the value of the submission. If I submit 'John', it will output 'John'. However, we also need to specify which input field this corresponds to. To do this, enter the name followed by an equals sign. The name you choose should match the corresponding data field in your Act-On proxy form.
• If the name in Act-On has a space, you'll need to encode it. For example, a space (' ') is encoded as '%20' since we can't put a space in a URL.
• An example that maps the value to First Name (note the '%20' encoded space)
  

  First%20Name={Name (First):1.3} 

• This will output 'First%20Name=John' in our example mentioned above.
• Do the same for your other fields, but separate them with a '&'. For example, here is what capturing first/last name and email could look like (note the ampersand characters):
  

  First%20Name={Name (First):1.3}&Last%20Name={Name (Last):1.6}&E-mail%20Address={Email:2}

Step 4:

On your WordPress page that form submitters will be sent to, paste in the following script anywhere on the page:

  <script>
  var aoExternalPostURL = "PROXY-URL-GOES-HERE";
  window.onload = function () {
  if (String(window.location).search("%40")>0) { 
  var aoUrlParams;var aoQuery = window.location.search.substring(1);
  (window.onpopstate = function () {var e, t = /([^&=]+)=?([^&]*)/g;
  aoUrlParams = {};
  while (e = t.exec(aoQuery)) aoUrlParams[encodeURIComponent(e[1])] = e[2]})();
  for (i in aoUrlParams) {var aoUrlParamsArray = aoUrlParams[i];
  try {document.getElementsByName(i)[0].value = decodeURIComponent(aoUrlParamsArray)} 
  catch (err) {}
  };
  var aoIfrm = document.createElement("iframe");
  document.body.appendChild(aoIfrm);
  aoIfrm.setAttribute("id", "ifrm");
  aoIfrm.style.backgroundColor = "transparent";
  aoIfrm.style.border = "none";
  aoIfrm.style.width = "1px";
  aoIfrm.style.height = "1px";
  aoIfrm.src = aoExternalPostURL + "?" + aoQuery;
  };
  };
  </script>

• Replace "PROXY-URL-GOES-HERE" at the top of your script with your proxy form URL (do not remove the quotation marks).

Step 5:

Save your changes, and test your form. It should now send form submitters to your response page, but now with their submission data passed through the query string in the URL. This will then be captured and sent to Act-On on the response page.

Standard Implementation: Redirect Method

Redirect lets you set any URL as the destination for visitors to be sent to, once they submit the form. If you are using this option:
 
Step 1: 

In Act-On, navigate to Content > Forms, and create a form with the fields you are hoping to capture and store in a list. Your website visitors will not see this form - it exists as a proxy used to receive data from Gravity Forms. Make note of the Data Field Name for each of your fields, as we will be feeding those Data Field Names into your Gravity Form.
 
Step 2: 

In the form editor (in Act-On), click Next to navigate to Settings. Under the Response Page section, look for Redirect to URL and paste in the URL you want your form submitters to be sent to once they complete your Gravity Form.
 
Step 3: 

In Act-On, navigate to Content > Form Post URLs. Generate an external post URL for the proxy form you created in Step 1.

• In the WordPress administrator interface, open up Gravity Forms and navigate to the Redirect confirmation behavior (steps to navigate there are described at the beginning of this article).
• In the Redirect URL input, paste in your Form Post URL that you generated in Step 1.
• Check Pass Field Data Via Query String. This will expose a text area with a drop-down icon floating to the right of the text area.
• Click this icon, and you will see a list of fields available in your Gravity Form.
• Click the field name in this list for each field you want to add. For example, this will add something like the following for the default First Name field:
  

  {Name (First):1.3} 

• With the above, this will pass the value of the submission. If I submit 'John', it will output 'John'. However, we also need to specify which input field this corresponds to. To do this, enter the name followed by an equals sign. The name you choose should match the corresponding data field in your Act-On proxy form.
• If the name in Act-On has a space, you'll need to encode it. For example, a space (' ') is encoded as '%20' since we can't put a space in a URL.
• An example that maps the value to 'First Name' (note the '%20' encoded space):
  

  First%20Name={Name (First):1.3} 

• This will output 'First%20Name=John' in our example mentioned above.
• Do the same for your other fields, but separate them with a '&'. For example, here is what capturing first/last name and email could look like (note the ampersand characters):
  
  First%20Name={Name (First):1.3}&Last%20Name={Name (Last):1.6}&E-mail%20Address={Email:2}
  
  

Step 4: 

Save your changes, and test your form. It should now send form submitters to your Act-On external post URL with their submission data passed through the query string. They will then be immediately redirected back to your own custom response page, allowing Act-On to capture data and convert your visitors to 'known', with no visual interruption.

Standard Implementation: Frequently Asked Questions

What is a query string?

By using web browsers, you have encountered a query string before. Here is a high-level overview of what a query string is:

• Query string – A line (string) of text that is used to pass information. For our purposes here, this is always done inside a URL.
  • For instance, when you search Google, you will see that your search terms are present in the URL when you look at the results. This is done via a query string.
  • https://www.google.com/search?q=search+term is an example of this
    • https://www.google.com is the domain and is not the query string. The query string is
      q=search+term
    • '?' indicates the start of the query string, and characters that can't go inside a URL such as a space are encoded or changed (' ' becomes '+').
• Field – The first part of a query string
  • In q=search+term, 'q' is the field
  • The format is field=value
• Value – The latter part of a query string
  • In q=search+term, 'search+term' is the value
  • If there are multiple fields and values, the format in a URL is: field1=value1&field2=value2&field3=value3 (full URL example is http://.domain.com/?field1=value1&fi...&field3=value3)
    • The query string starts with a '?' to separate it from the web page address, and each subsequent query string field/value pairs are separated by '&'
      
      

What is the difference between Redirect and Page? When should I use one or the other?

• Redirect functions by visitors completing your Gravity Form outside your domain briefly to your Act-On Proxy URL. This gives Act-On time to accept the data being submitted and to update the cookie on the visitor's browser. They are then sent back to your pre-defined response page, but the process takes a fraction of a second, and during that time you may see a rapid page navigation occur in the browser.
  • This method is fine for most. However, if you are interested in the fastest performance possible or are tracking bounces via a third-party service (such as Google Analytics), you will want to use Page in all likelihood.
• Page allows the form to submit data to Act-On without bouncing your site visitors outside your domain and onto the Act-On form response page. It is slightly faster as a result. It works by creating a hidden one-pixel iframe on your WordPress form response page that captures the query string in your URL and passes it to Act-On (the iframe being used allows us to update the visitor's browser cookie).
  
  

I'm using the Page steps and am unable to get the JavaScript to work on my response page. Why?

Running a unique JavaScript on a specific page in WordPress may require some setup if your WordPress account or configuration is set to disallow JavaScript by default. Web developers familiar with WordPress' PHP template files are encouraged to follow the official documentation provided by WordPress for embedding permanent scripts.

Why is my Form posting multiple times to Act-On?

Two most common causes for this issue:

• There is a hard line break in the javascript code that submits to Act-On
  • Solution: Remove the line break
• The form is using AJAX to submit (applies to Text method)
  • Solution: Do not use AJAX when inserting the form on the page, or choose another form post method if AJAX is required
    
    

For Web Developers: Gravity Forms API Integration

This strategy uses the Gravity Forms Developer: gform_after_submission hook, which will be added to your WordPress functions.php file. This allows you to make more flexible connections with Act-On that exist behind the scenes, and avoid having your WordPress set specific Gravity Forms settings via the Gravity Forms administration interface.

The example below is adapted from the PHP sections of the article Posting External Forms to Act-On

Step 1:

For each form this is used with, we need an equivalent "mirror" version of the Form to be created within Act-On. For example, if your custom form on your website captures First Name, Last Name, and Email, you'll need to create a form within Act-On that also requests these fields. Your website visitors will never see this Act-On variant of your form -- we simply need to receive your custom form’s data.

In each field in your Act-On "proxy" form, note the "Data Field Name". You can see the Data Field Name by clicking each form field in the form editor to bring up the field settings. We will need this Data Field Name in the functions.php code addition below.

Step 2:

Get your Act-On form's external post URL. This is located under Content > Form Post URLs. The external post URL is unique from your form's public URL and is designed specifically for accepting incoming external submissions.

Step 3:

In your WordPress admin interface, navigate to the editor for your Gravity Forms and note the field IDs. Your field ID can be seen in the header of the Gravity Forms form editor if you click it to expand it.

Step 4:

Paste the following code into a valid spot of your theme's functions.php file:

Class to implement: 

  /* Post form submission data to Act-On and convert visitors to known via 1px
  by 1px hidden iframe that is 
  * generated programatically. The iframe src contains a query-string to pass form
  field values into Act-On.
  * Assumes PHP version 5 or newer
  */
  
  class ActonWordPressConnection 
  
  {
    private $_postItems = array(); 
    private function getPostItems() 
    {
      return $this->_postItems;
    }
  
    /**
   * for setting your form's POST items (key is your form input's name, value
  is the input value)
    * @param string $key first part of key=value for form field submission
  (name in name=John)
    * @param string $value latter part of key=value for form field submission
  (John in name=John)
    */
    public function setPostItems($key,$value)
    {
      $this->_postItems[$key] = (string)$value;
    }
  
    /**
    * process form data for submission to your Act-On external form URL
    * @param string $extPostUrl your external post (Proxy URL) for your Act-On
  "proxy" form
    */
    public function processConnection($extPostUrl)
    {
      $fields = http_build_query($this->getPostItems()); // encode
  post items into query-string
      $extPostUrlWithQueryString = $extPostUrl . '?' . $fields;
  // assemble full URL w/ query-string of submission key-values for GET to Act-On
      $hiddenIframe = "<iframe style='position: absolute; bottom:
  0px; right: 0px; border: none; height: 1px; width: 1px; background: none' src="
  . $extPostUrlWithQueryString . "></iframe>"; // assemble hidden iframe
  containing URL to pass form submission data and update visitor's cookie value
  thru iframe
      echo $hiddenIframe;
    }
  }

If you do not have a preferred location for custom classes, this can be pasted at the bottom of your functions.php file (but before the closing "?>" tag -- we don't want to remove that!). You only need to paste this code in once.

Note: This is the same class as is utilized for the WP-members API integration, though implementation is different for Gravity Forms (to accommodate the Gravity Forms API).

An example implementation of the above class:

  add_action('gform_after_submission', 'send_to_acton', 10, 2);
  function send_to_acton($entry,$form) 
  {
  // declare new ActonWordPressConnection object
  $ao_gf1 = new ActonWordPressConnection;
  
  // format: setPostItems('your Act-On data field name','your custom form html
  input name')
  $ao_gf1->setPostItems('First Name', rgar( $entry, '1.3' ) ); // HTML input name attribute
  is "First Name", Act-On data field name should match that
  $ao_gf1->setPostItems('Last Name', rgar( $entry, '1.6' ) ); // please note that Act-On
  does not accept filed names with punctuation marks in them, so rename as necessary
  $ao_gf1->setPostItems('E-mail Address', rgar( $entry, '2' ) );
  
  // processConnection method, with your external post URL passed as the argument
  $ao_gf1->processConnection('http://www.actonsoftware.com/acton/e...01/d-ext-0001');
  }

Please reference the code notes for the above. Remember to reference your specific input's Data Field Names as the first argument for each setPostItem.

Regarding field names for Gravity Forms: Note how they use digits for some fields (such as X.3 or X.6 for first and last names). You can read more about these entry objects here, but here is a quick overview of them:

• In the Gravity Forms First/Last name block (where you have both first and last names in the same block), your first name will be X.3, and your last is X.6. X is your field ID, as shown earlier in this article.
• For checkbox blocks in Gravity Forms, your first checkbox is X.1, your second checkbox is X.2, and so on. Please see Frequently Asked Questions in the External Posting article for more information on handling checkboxes, as they are slightly different from other field types.

If you have multiple Gravity Forms, you will want to create a new class implementation for each form. You will also want to adjust the gform_after_submission API hook function name to reference a specific Gravity Form in cases where you have more than one form on your WordPress site.

Web Developer Resources

• Gravity Forms Developer: gform_after_submission hook (outside link)
• Gravity Forms Developer: entry object (outside link)