Page title

Get started

Let's get started by pretending this page is part of a careers site where job seekers can search for the ideal role. We've added some basic filters and data for this demo. On the right you'll see our example form with filters and at the bottom you'll find the search results. Upon submitting this form, it will redirect back to this page with a modified URL and you'll see the filtered search results.

Below, you'll learn the details of how this works.

Step 1: Add new form fields that you'll use as filters

First, you'll need to decide how add new form fields to either contacts, a new search object. (You can also of course use the fields of the object you want to filter.)

You'll want to make sure the fields you add match the fields of the dynamic block object you want to filter. This is because will be using the results of these form submissions in our URL so that our dynamic blocks know what to filter by.

In this example, we will be adding the fields to contacts to make it easy. We will be merging into one single example record every time so that new contacts don't get created for every search. If you want to get

Reasoning: We need to add fields on the form to filter off of, but we don't want to use the dynamic object record fields on the form since we don't want to update those records. Instead, we'll use Contact merge fields to update the URL upon form submission with the filter values we need.

Example: Our example will be around job listings. We'll use the following fields that are found in our "job listing" object and recreate those in the Contact object. Below are the "Job listings" fields that we'll recreate in the Contact object.

Fields created in Job listing

Fields recreated in Contact object

Tips
1. Make sure the field names and field options are listed exactly as they are found in the corresponding object that you want to filter results for.

2. For the "sort by" field, the options are either "Ascending" or "Descending". That's because in a later step, we'll add the merge field in the URL to sort by what a user selects in this field. But the sortBy variable works off of "Ascending" or "Descending", so we have to merge one of those values into the URL in order for it to work properly.

Step 2: Create the "filter" form

1. Add the newly created Contact fields from step 1 onto the form.
2. You can choose to have the resulting dynamic records on a different page. Or, you can show results on the same page. For this example we'll show results on the same page. And while it's not required, it's recommended you add in the "Job listing" merge field into the dynamic block for each field you're going to be filtering. This makes it easy to see the results.
3. Add a submit button.
4. Publish the page to a URL. We'll be using the published URL in step 3 below.

Example (image) of form with Contact fields added

Step 3: In form settings, create the custom URL with the corresponding merge fields

1. The next step is to formulate the URL and add it into the 'Custom URL' section of the form settings. This allows for people to enter in values into the form, and have the URL populate with those values in order to display only the records that match.

2. It's worth mentioning the basic variables and the basic format. "searchFor" variables allows users to search for certain values, and the results will display if ANY of the searchFor values match. "searchFilter" is very similar, except results will only display if ALL of the searchFilter values match. (Think amazon or any mainstream website where you need to filter your results...that's the idea here)

3. Before we create the URL, the basic format for both searchFor and searchFilter is "searchFor" or "searchFilter" followed by "=", followed by the field you're searching for, followed by a colon, followed by the value you're searching for. Example: searchFilter=Field name:Value NOTE: Non-text fields can use certain delimiters that use something other than a colon. Refer to the advanced tips section for reference.

4. Now that we understand the basic formatting, we're ready to create the the URL. Click into the form settings, click the 'Custom URL' option, then click into it.

5. First, add the published page's domain. In our example, the domain is https://joblistingpage.safechkout.net/.

6. After the domain, add a '?'. So it's https://joblistingpage.safechkout.net/?

7. On our example page, we're going to have the 'Job title' use the searchFor variable, so that we can search for a job title and see any results that match, plus only include the additional filter values. If we wanted to include 'Job title' as a searchFilter, we could do that also, so we would only see results that match that job title and any of the other filters.

We'll take our URL "https://joblistingpage.safechkout.net/?" and add searchFor=Job title:", so the full URL will be: https://joblistingpage.safechkout.net/?searchFor=Job title:

8. Next, we need to add the filter variables for each field that's on the page/each field that we want to filter off of. So using the URL up to this point, we'll add a "&", followed by "searchFilter=", followed by the field name, followed by a colon, followed by the merge field. Below I'll list out some examples

9. Using the URL from step 7, we'll follow the same format for the "Department" field. So we'll take our URL, add a "&", followed by "searchFilter=", followed by the field name, colon, merge field. So the URL: https://joblistingpage.safechkout.net/?searchFor=Job title:

will become: https://joblistingpage.safechkout.net/?searchFor=Job title:&searchFilter=Department:.

10. We'll repeat this until we have each field added. However, instead of adding a new searchFilter for each new field, we can separate fields and values with semicolons. So to add the "Experience" field to the URL from step 9, it will become https://joblistingpage.safechkout.net/?searchFor=Job title:&searchFilter=Department:;Experience:.
Repeat this same format for all fields on the form.

11. Note on numeric and price fields: In our example, we're using "Minimum salary". So we can use searchFilter=Minimum salary:value, and that will filter records for that exact value. However, people may want to see any salary equal to or greater than the value. In that case, instead of adding a colon, we can add a ">=". So it will be searchFilter=Minimum salary>=value. Using >= is HIGHLY recommended, because if you don't fill out numeric field, the merge field will still populate as 0. And unless the "minimum salary" is equal to 0, no results will display. Refer to advanced tips section for the other numeric delimiters.

12 We also have two additional fields called 'Sort by' and 'Sort order'. You may have noticed that these fields weren't in the Job listing object. That's because these fields and the corresponding values will allow us to sort by a particular field, and sort either ascending or descending. And they don't need a value in the record object to make this work. We just need these fields in the Contact object in order to make them work off of the form submission. In the sort by field, we have "Department" and "Salary". In sort order, the values are "Ascending" and "Descending".
The format for sort by is sortby=
The format for sort order is sortorder=[Sort by minimum salary]
They essentially follow the same format as other fields, except it's the sortby or sortorder variable name, followed by equal sign, followed by the value.
The only values that will work for sortorder are "ascending","descending", "desc", or "asc". So those values must be in the Contact field on the form in order to work.
The sortby field values must be one of the field names that exist in the job listing object, because we're choosing to sort based off of one of those fields.
Both of these options exist in dynamic block display settings, but by adding them into the URL, they'll overwrite the block settings and sort the records based on values in the form.
We also want to add these to the end of the URL. The reason we add this to the end is because if you have multiple sortBy variables in your URL and they're not targeting a specific block, they could have conflicts. And we'll only use the lasts sortBy variable found in the URL in that instance. So it's not required but recommended to add them to the end of your URL, unless you're including these variables in different blocks.

12. Once you've added all of the fields from the form, the full URL should be: https://joblistingpage.safechkout.net/?searchFor=Job title:&searchFilter=Department:;Experience:;Location:;Minimum salary>=;Education:;Degree required:No&sortBy=&sortOrder=[Sort by minimum salary]

Step 4: Add value into hidden fields section

Now that we have the custom URL redirect possible, there's another step that's not required but recommended.

1. In the hidden fields section, click into the dropdown, choose the Contact email address, and enter in an address not tied to a contact. In our example, we're using "searchtest@ontraport.com"
Reasoning: If you do not take this step, and you don't have an email address field on the form, every new form submission will create a new record. And that can cause users to go over their limit which isn't ideal. Therefore, we just want to link all of these form submissions to the same record. Both so new records aren't created, and to get a sense of what our visitors are searching for. Meaning we can check the automation logs and see exactly what they were trying to filter.

Optional: Step 5 - Add a clear results button

Sometimes visitors will perform a search, and then they'll want to clear the results again before performing another search. So it's not required, but recommended you do the following:
1. Add an additional button (not submit button) element beneath the submit button on the form.
2. Label the button element something like "Clear results"
3. Hyperlink the button to the base URL of the search page. In this case, it's https://joblistingpage.safechkout.net/?.
4. Now when users click this button, they'll be taken back to the page without any filters.

Advanced tips and examples

1. Non text field delimiters - For non-text fields, we can use the colon to signify "this field is equal to this value". However, there are additional delimiters that we can add to non-text fields to filter off of.

Date/Date and time fields:

After date: searchFilter=Field name>MMDDYYYY
Before date: searchFilter=Field name<MMDDYYY
On or after date: searchFilter=Field name>=MMDDYYYY
On or before date: searchFilter=Field name<=MMDDYYYY
On the exact date: searchFilter=Field name:MMDDYYYY
Not on the exact date: searchFilter=Field name!=MMDDYYYY

Price and number fields

Greater than: searchFIlter=Field name>number
Less than: searchFilter=Field name<number
Greater than or equal to: searchFilter=Field name>=number
Less than or equal to: searchFilter=Field name<=number
Equal to: searchFilter=Field name:number
Not equal to: searchFilter=Field name!=number

2. Include various field types - Only certain field types can be searched/filtered. Below are all of the available fields

Address
Checkbox
Country
Date
Date and time
Dropdown
Email
List selection
Long text
Numeric
Tags
Phone
Price
Rich text
SMS
State
Text
uniqueID
URL
Related object data that's one of the above field types (Any object that can be drilled into from the block object. This includes both 1-1 related objects and parent objects)

3. DATE FIELDS ISSUE: Right now, merge fields populate with dashes (1-2-2023). However right now filter format for date fields is MMDDYYYY, without dashes. This is being worked on but just noting date fields will not work properly on a form to filter.
4. Capitalization for searchFor, searchFilter, sortBy, sortOrder, startOn, doesn't matter. HOWEVER, field names and field values are case sensitive.
5. Targeting specific blocks. Add brackets, [] with the block ID in between, directly after searchFilter. Example: searchFilter[123456]=Field:Value will only target that specific block. You can target multiple blocks with the same searchFilter variable by separating the block IDs with commas. So searchFilter[123,456]= will target both block ID 123 and block ID 456. You can mix and match to include block ID's on some searchFilter variables and not others.
6. You can filter fields that aren't necessarily displayed on the page. Meaning if you add searchFilter=Department:Operations, and the 'Department' field isn't displayed in the dynamic block but it's a field in the records, any record that has "Operations" in the department field should still display
7. Note, if you don't submit certain fields on the form, they have a default value still. Meaning if you have searchFilter=checkbox:[Checkbox], and you don't fill that field out, it will populate automatically as searchFilter=checkbox:No. Also with numeric fields, if you don't enter in a value, it will populate as 0. Things to keep in mind.
8. Available sort variables - We already covered 'sortBy', but we want to quickly cover all of the other sort variables.
"sortOrder" - Add this variable to sort
5. If you include multiple sort variables, and they're not targeting specific blocks, if there's conflicts (multiple sort variables), we'll use the sort variables that appear last in the URL.

Example

The way this works is simple. We take the values from the form fields below and put them into this form's destination URL along with special keywords.

On that page lives a dynamic block with all the records we want to search. This is our "search results" page.

When the page loads, the custom URL is read, & only the records that match the values in the URL are shown!

Job title

Minimum salary

Education

Degree required

Submit

Clear results