This article is intended to assist technical users and developers working with websites and third-party applications to embed Pipeliner Online Forms.
Pre-fill Parameters and How to Use Them
For developers who require full control over field mapping within an Online Form, Pipeliner offers a comprehensive method for performing field lookups and pre-populating form data via JavaScript. This article will step you through the process of accessing references for any field within an Online Form and mapping those references into a URL query string, as well as mapping the references within the HTML layer of a web page in order to pre-populate your form.
The list of Pre-fill Parameters that can be used for your Online Form can be accessed via the 3-dot icon in the top-right area of the Online Form editor. ⤵
In the resulting popup, you will first select an option from the "Select part of the form" dropdown list, which will then display the related reference value(s) for the field. ⤵
There are two types of field references that come into play -- Link and Embedded. There is a small variation for each field reference seen in the resulting Pre-fill Name column depending on whether the reference will be used within a URL link or within embedded web page code. ⤵
Name - This is the Question Title that you have applied to the related field in your form.
Pre-fill Name - This is the reference that you will include in your URL or embedded code.
Field Options - This block is visible only for Dropdown lists, Radio Button lists, or Multi-Select Checkbox fields. The first column will display the field option name and the second column will display the ID of the option. The Option ID must always be used when prefilling your online form via JavaScript. ⤵
Personalization - This block will only be visible if the form field includes customized record mapping within the Question Title or Question Description. ⤵
Example of URL with pre-fill parameters
https://example.com/view-form?
cf_first_name=John&
cf_last_name=Doe&
cf_tshirt_size_contact_id=01889b11-cc4e-fff1-5bad-4d3d31937c93
Example of Embedded code with pre-fill parameters
<ppl-online-form-embed id="bbe744baca1f36c9d55b"
data-cf_first_name="John"
data-cf_last_name="Doe"
data-cf_tshirt_size_contact_id="">
</ppl-online-form-embed>
Embedding an Online Form via JavaScript and Data Pre-Fill
In order for you to embed an Online Form on your website, click the 3-dot icon in the top-right area of the Online Form editor and click the "Get Embedded Code" option. ⤵
In the resulting popup, follow the steps to embed the Online Form on your website. The "Show pre-fill" option at the bottom-right of the popup allows you to select specific fields that can then be used to auto-fill your form when the visitor hits your web page. ⤵
Pre-fill on Form Initialization
You can populate the "Pre-fill" values in your embedded code when the Online Form is initially loaded by using a "custom_value" placeholder, or the ID for a Dropdown list, Radio Button list, or Multi-Select Checkbox field.
Code Example (pre-filling fields on form initialization):
//Online Form SDK
<script src="https://static-webapps.pipelinersales.com/online-form/production/latest/online-form.js" defer></script>
//Online form was initialized on website with ID=bbe744baca1f36c9d55b
<ppl-online-form-embed id="bbe744baca1f36c9d55b" >
</ppl-online-form-embed>
//Dropdown, Radio Button, Multi-select checkbox requires Field Option ID for correct population
<ppl-online-form-embed id="bbe744baca1f36c9d55b"
data-cf_satisfaction_rating="custom_value"
data-cf_first_name="custom_value"
data-cf_last_name="custom_value"
data-dropdown="01889b11-cc4e-fff1-5bad-4d3d31937c93"
data-contact.2853409f-dc70-002c-e9ba-c91f4649cb7b="custom_value"
data-record-id="">
</ppl-online-form-embed>
custom_value - These values are always validated, so if (for example) your Online form expects a field value to be formatted as an email address, it will display an error in the Online Form if the inputted value doesn't conform to the required formatting.
Pre-filling and working with values after Form initialization
Pipeliner's Online Form SDK, includes a 'setInputData' function to update values within the form after the online form has been initialized. This function can also modify fields that aren't visible within the form, such as a field that was marked as "Invisible" in Online form editor.
Function setInputData:
setInputData(pre_fill_parameter_field_name, new_value)
pre_fill_parameter_field_name - This represents the field name.
new_value - This represents the custom value for the field. Just as with the custom_value option seen in the "Pre-fill on Form Initialization" earlier in this article, the new_value is always validated, so if the question expects a value to be formatted as an email address, a validation error will be seen in the Online Form when an attempt is made to submit the form and the formatting of the input is invalid.
NOTE: For Dropdown, Radio Button, Multi-Select Checkbox fields, you must provide the Field Option ID to pre-fill the field correctly.
Code Example (pre-filling after form initialization):
//Online Form SDK
<script src="https://static-webapps.pipelinersales.com/online-form/staging/latest/online-form.js" defer></script>
//Online form was initialized on website with ID=bbe744baca1f36c9d55b
<ppl-online-form-embed id="bbe744baca1f36c9d55b" >
</ppl-online-form-embed>
//Function SetInput Data is Called on the initialized online form
<script>
document.addEventListener('DOMContentLoaded', (event) => {
document.getElementById('bbe744baca1f36c9d55').setInputData('cf_first_name', "John");
});
</script>
Use Case: Record Identification via Record ID
A common use-case scenario will be to send an email blast with a unique identifier mapped inside a URL link within the message. This could simply map the Record ID in order to update the related record with any input for the form, but it can further be used to pre-populate your embedded form with data from the related record.
Pipeliner has two methods to ensure that your Online Form is always linked to the correct record. The first method is to use the data-record-id attribute in your Online Form and then create a link to the form using the record-id reference within an email message.
In the following example, the related Account ID is captured in the email message using the record_id reference as part of a URL link. ⤵
The link will then appear as such. ⤵
When the recipient clicks the link in the email message, they are then redirected to the Online Form on your website and the form will capture the Record ID using the parameter data-record-id as seen below. ⤵
<ppl-online-form-embed id="bbe744baca1f36c9d55b"
data-record-id="record_id_value">
</ppl-online-form-embed>
NOTE: record_id_value is the ID of the record retrieved from the URL in your web browser address bar, which traces back to the record_id reference in your email message's URL link.
A second method for ensuring that your Online Form is always linked to the correct record is by using paired fields, which can be configured within the settings of the Online Form editor. ⤵
Use Case: Populating Data in an Embedded Online Form using URL Parameters
The standard use-case scenario for an embedded form is to automatically pre-populate data from a URL. For this to be successful, a valid URL must be provided.
As a developer, you have two options for populating data within an Online Form: either using on form initialization, or post-initialization using the setInputData function.
Example of a URL where the embedded form should be rendered upon initialization:
https://example.com/view-form?
cf_first_name=John&
cf_last_name=Doe&
cf_tshirt_size_contact_id=01889b11-cc4e-fff1-5bad-4d3d31937c93
Data is then pre-populated upon form initialization using embedded code:
//Online Form SDK
<script src="https://static-webapps.pipelinersales.com/online-form/staging/latest/online-form.js" defer></script>
//Dropdown, Radio Button, Multi-select checkbox requires Pre-fill Option ID for population
<ppl-online-form-embed id="bbe744baca1f36c9d55b"
data-cf_first_name="query_parameter_value_first_name"
data-cf_last_name="query_parameter_value_last_name"
data-dropdown="01889b11-cc4e-fff1-5bad-4d3d31937c93"
data-contact.2853409f-dc70-002c-e9ba-c91f4649cb7b="query_parameter_value"
data-record-id="query_parameter_value">
</ppl-online-form-embed>
* query_parameter_value represents values retrieved from the URL in your browser.
Example of code for populating data after form initialization:
//Online Form SDK
<script src="https://static-webapps.pipelinersales.com/online-form/staging/latest/online-form.js" defer></script>
//Online form was added into the HTML, with ID=bbe744baca1f36c9d55b
<ppl-online-form-embed id="bbe744baca1f36c9d55b" >
</ppl-online-form-embed>
<script>
document.addEventListener('DOMContentLoaded', (event) => {
const params = new URLSearchParams(window.location.search);
document.getElementById('bbe744baca1f36c9d55b').setInputData('cf_first_name', params.get('cf_first_name'));
document.getElementById('bbe744baca1f36c9d55b').setInputData('cf_last_namee', params.get('cf_first_name'));
document.getElementById('bbe744baca1f36c9d55b').setInputData('01889b11-cc4e-fff1-5bad-4d3d31937c93', params.get('cf_tshirt_size_contact_id'));
});
</script>