What Picklist? Dynamic Form Fields in Oracle Eloqua
Scott Winterton
Co-Founder @ Kahuoi | Turning Sales Contacts into Connections with AI
Disclaimer: this article includes commentary and instruction related to customizing Oracle Eloqua landing pages. While I am an Oracle employee, all content, commentary and advice is my own, and should not be officially viewed as implementation advice or support guidance.
I'm taking a quick break from writing on sales enablement to cover a frequent question I get from marketers using Oracle Eloqua for omni-channel campaign automation. If you're familiar with Eloqua, you know that its primary benefits are simplicity and flexibility. It's a great tool for marketers who want to create an entire personalized customer experience with no coding or IT intervention, but it also offers the flexibility to significantly extend the omni-channel experience if you do want to customize it.
Eloqua's asset design editors were created so that a marketer can create a personalized and interactive experience for each audience member entirely using business configuration rules. But what do you do if you want to turn that experience up a notch? A common request I hear in that regard is, "how do I control the display and behavior of dropdown lists and dependent fields in Eloqua forms?"
The good news (and the bad news) is that, with a little bit of JavaScript, this is actually quite simple. In this article I'll walk through some examples and usable, published libraries that will help you to show and hide fields, and how to ignore the Eloqua picklist entirely so that you can create your own dropdown list values for a form. In our example, we are going to control the behavior of the State or Province field based on the value the user selects for the Country field.
One last thing... below are high-level, step-by-step instructions on how you might go about adding dynamic capabilities to your Eloqua landing page. Please feel free to reach out or add comments below if you need additional assistance. I've also published some of these capabilities, and will include an easy shortcut for this use case later in the article.
1. Preparing to customize your landing page
The first step in customizing your landing page is to add an event handler. An event handler, simply put, tells the browser to how to respond based on a user's behavior, such as moving or clicking their mouse, interacting with forms, or typing on the keyboard. Event handlers can also affect the user's experience when a page or image loads. Within Eloqua, you will add your event handler to the "Open JS Editor" section in the Design Editor, or within your <head> tag in the HTML editor.
In our example, we are going to add an event handler when the page loads. This tells the browser that we will want it to call the "load" function when the page loads. The preparePageLoad function adds the event listener to the browser window, and tells it to run the load function.
When the load function executes, the document.getElementsByName function looks for an element on the page called "country." If you have not modified the HTML Name in your Eloqua form, this is the default name for the country field. If you have modified the HTML Name, you can set your JavaScript to look for the modified name.
In my example, I included a loop, in case the page includes more than one form. The getElementsByName function returns an array that includes every instance of an element named "country" on the page. So if you have more than one form, it may return more than one element. In this example, it will add an event listener to each occurrence of the "country" field. I told the event listener to look for the "change" event for the country field, so that the setStateOrProvinceFromCountry function will execute when the value of the field changes. I also call the setStateOrProvinceFromCountry function once by default, in case the country is pre-selected.
When the setStateOrProvinceFromCountry function executes, we will do two things: one basic, one fancy. First, I'll explain how we show or hide a field based on another field's value. Then we'll cover how to override the Eloqua picklist to show our own values in a field.
2. Show or hide a field based on another field's value
When we call the setStateOrProvinceFromCountry function, we will use the getElementsByName and getElementById functions to find the value of the "country" field. In my example code I take an extra step that we're not covering yet: I look at an external list of countries and determine whether I need to show states or provinces. We will cover external lists in a later article, but since that part of the code isn't pertinent to the article I haven't covered it here. The outcome of that code is a "countryType" variable that lets us decide whether to show or hide two fields on our form. For this example I used separate "state" and "province" fields, and will show or hide them based on the value of the "countryType" variable.
In this example, we will use the getElementsByName function to look for the default Eloqua "State or Province" field from the form editor. If it finds an element that uses the Eloqua default HTML "stateProv" name, it will not try to show or hide any fields. If it does not find one, the code assumes that you are using separate "state" and "province" fields, so we need to show or hide them accordingly using the setElqFormElementDisplay function.
When we call the setElqFormElementDisplay function, we pass it two parameters. The first is the HTML Name for the element as it was defined in the Eloqua form editor. The second is whether we want to show or hide the control. We use "none" to hide and "block" to display the control, as it these correspond with display properties in the page's stylesheet (CSS).
In my example I broke the function up to make it reusable, so you will notice that the setElqFormElementDisplay function calls another function, getElqFormElement, before it shows or hides the field. The reason is that if we show or hide the element we just passed to the function, it will only hide the control, leaving a blank space in its place. We need to use the Document Object Model, or DOM, to find the rest of the HTML code that served as a placeholder for your control.
Each control in an Eloqua form sits inside a tag with the id of "formElement," followed by a number that represents the order in which it is displayed by default on the form. The getElqFormElement function searches the HTML for the correct tag and passes the result back to the setElqFormDisplay function. Now instead of hiding just the control, we can hide the control and collapse any resulting whitespace.
3. Control dropdown list values
In the previous example, we displayed distinct "State" and "Province" fields when we select a value in the "Country" list. The next step is to assign new values to the dropdown list. Since we have already seen how to identify an element using getElementsByName and getElementById, this is relatively easy.
Earlier we used the Document Object Model to find the "parent" element to a form control so that we can more gracefully hide and show form elements. We can think of a parent element as "moving up" in the DOM. Similarly, we can "move down" to a child element in the DOM using the children attribute.
When working with a dropdown list, we will have multiple options associated with the list. Before we can add our own, we need to remove the values already in the picklist. To do this, we will use a loop to remove all of the options related to the list. The for portion of this code loops through all of the child options and removes them.
Next, we need to add new options. In my example I got my options from an external file, but you could also include them directly in your code. I will cover the external file option in a later article.
When we create the options for our dropdown list, we can either add them one by one or as part of a loop. In my example I got my list of states and provinces from an external file and pulled them into the "list" array. The loop at the bottom of this code block sets the "name" and "value" attributes for each option and adds each one to the dropdown list.
A bit of good news
So you've read through this and you may be thinking to yourself, "I really want to do this, but I don't want to write my own code." If you're in that boat, I've got a bit of good news for you. To begin with, I published a library that supports this use case. Today it's setup to support either the default "State or Province" field or distinct "state" and "province" fields and, best of all, you can implement it using two lines of code:
Once you've implemented this code on any landing page by including it in the JS Editor of the design editor or the <head> section of your HTML editor, it will automatically:
- show or hide a field with the name "state" or "province" based on the value of the "country" field on your form
- Automatically populate your state, province, or the default "State or Province" field with relevant options based on the value of the "country" field
If you'd like to see the code in action, please feel free to visit scottwinterton.eloquademo.com/earthmovers-webinar
One last thing...
This is just one example among many related to dynamic or dependent fields. If you have any comments, anything you'd like to see added to my library, or need some additional guidance, please feel free to comment below or reach out through LinkedIn. If you do reach out, please be aware that any advice, guidance or support I provide is my own, and should not be interpreted as implementation guidance or consultation from Oracle.
SEO Manager @ Logos
3 年Hi Scott Winterton, thanks for the resource! I realize I'm about three years behind, but I have a question related to this kind of dynamic form field in Eloqua. Any chance you'd be available to connect to talk through it?
Marketing AI, Technology & Transformation Consultant | Super Problem Solver | Friendly Entrepreneur
6 年Thanks Scott!!
Global Healthcare Digital Experience, Technology and Operations Leader | Speaker | Family Guy | Adventurer | Musician | DIY | Dr Pepper Fan
6 年Awesome post!!! This takes me back to classic top liners days. There needs to be more of this community innovation and sharing to push the envelope of what’s possible. Thanks Scott!!!
Advisor to GTM Teams
6 年Thanks for posting the sample code Scott!