Skip to main content

Address Widget

BallotReady provides multiple iterations of our widget code to ensure that there's a version that fits well with your website and your purposes. We'll go through these from most recommended to least recommended, but here's a comparison of these three versions:

LevelRequires <head> codeSecurity levelUser info fieldsAuto-ResizingUTM code compatible
🥇 GoldHigh
🥈 SilverMedium
🥉 BronzeHigh

Gold Level Widget Instructions#

Step One: Include supporting scripts#

Please add the below lines of code to the <head> section of your website’s HTML. Depending on what you used to build the site, this may have to be added somewhere in a UI. The URL you should use in each case is the draft site URL you were sent by your point-of-contact (usually taking the form app.clientname.civicengine.com or ec.clientname.civicengine.com)

<script  src="https://app.clientname.civicengine.com/embed.js"  async  defer></script><link  rel="stylesheet"  media="screen"  href="https://app.clientname.civicengine.com/embed.css"/>

Step Two: Add widget element#

Please add a <div> like the one below wherever you want your widget to show.

<div  class="civicengine-address"  data-input-email="required"  data-input-first-name="required"  data-input-last-name="required"  data-input-notifications-opt-in="optional"  data-input-phone="optional"></div>

This code specifies the content of your widget. The above code is just an example, you can choose to include as many fields as you'd like. You can find a full description of the fields you can include and how to include multi-language capability for your widget in the Widget Element Content section.

You can play around with these fields and how they'll appear in the Widget Playground.

Step Three (optional): Additional styling#

You may want to format the div that surrounds the widget. You can wrap the div we sent you originally in another div and give it the styles you prefer. Below, you can see the styles we used on our test site; you can put this style in the head or in your own stylesheets.

/* Customer can control widget dimensions by wrapping it in a div with their ownCSS */<style>  .pledge-container {    background: #ececec;    margin: 0 auto;    max-width: 500px;    padding: 1rem;    border-radius: 0.3rem;    opacity: 0.95;  }</style>

If you'd like to incorporate the styling, you'd wrap the code you selected in step 2 with another div for the the .pledge-container styling. That would look something like this:

<div class="pledge-container">  <div    class="civicengine-address"    data-input-email="required"    data-input-first-name="required"    data-input-last-name="required"    data-input-notifications-opt-in="optional"    data-input-phone="optional"  ></div></div>

Silver Level Widget Instructions#

The Silver level widget instructions are intended for customers who still want to have a widget with customizable fields, but are using a website building platform where you can't inject code into the /head section of the site. Therefore, this widget is implemented in the same way as the Gold Level widget, but with the code that would normally go in the head section in the body section of the page. This code would look the same as the code generated in the Gold Level Widget Instructions, but all in the body of the section of the page instead of in different pages. The URL you should use in each case is the draft site URL you were sent by your point-of-contact (usually taking the form app.clientname.civicengine.com or ec.clientname.civicengine.com)

Option 1: Widget box without styling#

The simplest way to configure this code is without the styling we provide. You can customize the widget element with the attributes described above. Here's an example of what that code would look like:

<script  src="https://app.customer.civicengine.com/embed.js"  async  defer></script><link  rel="stylesheet"  media="screen"  href="https://app.customer.civicengine.com/embed.css"/>
<div  class="civicengine-address"  data-input-email="required"  data-input-first-name="required"  data-input-last-name="required"  data-input-notifications-opt-in="optional"  data-input-phone="optional"></div>

Option 2: Widget box with styling#

Just as in the Gold Level instructions, you can include styling for the widget to change the background, the width, and other attributes. If you would like to include this, that code would something like this:

<script  src="https://app.customer.civicengine.com/embed.js"  async  defer></script><link  rel="stylesheet"  media="screen"  href="https://app.customer.civicengine.com/embed.css"/><style>  .pledge-container {    background: #ececec;    margin: 0 auto;    max-width: 500px;    padding: 1rem;    border-radius: 0.3rem;    opacity: 0.95;  }</style><div class="pledge-container">  <div    class="civicengine-address"    data-input-email="required"    data-input-first-name="required"    data-input-last-name="required"    data-input-notifications-opt-in="optional"    data-input-phone="optional"  ></div></div>

Bronze level Widget Instructions#

This widget is the simplest because it simply embeds a page into your page. However, you will not be able to add additional fields to the widget. To do this, add an iframe like the one below wherever you want your widget to show.

<iframe  src="https://app.customer.civicengine.com/w/address/"  style="background: transparent; border: none; height: 150px; width: 100%"></iframe>

Reference#

The Gold and Silver level widgets are best because users can customize the behavior of these widgets the most. To do this, you can include different widget attributes in the "civicengine-address" <div> .

User data attributes#

Here are the different attributes you can use to include different user data fields. Each of these can be set to optional or required.

AttributeValue optionsDescriptionExample
data-input-first-name"optional","required"creates first name field<div class="civicengine-address"
data-input-first-name="optional"
data-input-last-name="optional"
></div>
data-input-last-name"optional","required"includes last name field<div class="civicengine-address"
data-input-first-name="optional"
data-input-last-name="optional"
></div>
data-input-email"optional","required"creates email field<div class="civicengine-address"
data-input-email="required"
></div>
data-input-phone"optional","required"includes phone number field<div class="civicengine-address"
data-input-phone="optional"
></div>
data-input-notifications-opt-in"optional"creates check box with
custom text (default
"Sign up for updates
from the campaign")
<div class="civicengine-address"
data-input-phone="optional"
data-input-notifications-opt-in = "optional"
></div>
data-input-custom-field"optional","required"includes dropdown with custom values1 (default preview text: "Select an option...")<div class="civicengine-address"
data-input-custom-field="optional"
></div>

UTM code attributes#

You can now pass UTM codes either through the URL or through the widget. This is especially useful if you're sharing your widget code with partners in order to track users on different platforms. However, URL UTM passing and widget UTM passing cannot be used together and the widget UTM codes will override the URL. If you pass utm_source = "facebook" in the URL, and utm_medium = "ballotbox" in the widget, your user data will return "utm_source" = "null" and "utm_medium" = "ballotbox". If you'd like to learn more about passing UTM codes in the URL instead, or about UTM codes in general, check out our helpdesk article.

AttributeValue optionsDescriptionExample
data-utm-source"social"Sets the utm_source parameter that is passed to BallotReady. If any UTM parameters are used, it will overide those actually in the URL<div class="civicengine-address"
data-utm-source="yourUTMSource"
></div>
data-utm-medium"facebook"Sets the utm_medium parameter that is passed to BallotReady. If any UTM parameters are used, it will overide those actually in the URL<div class="civicengine-address"
data-utm-medium="yourUTMMedium"
></div>
data-utm-campaign"GOTV"Sets the utm_campaign parameter that is passed to BallotReady. If any UTM parameters are used, it will overide those actually in the URL<div class="civicengine-address"
data-utm-campaign="yourUTMCampign"
></div>
data-utm-content"ballotbox"Sets the utm_content parameter that is passed to BallotReady. If any UTM parameters are used, it will overide those actually in the URL<div class="civicengine-address"
data-utm-content="yourUTMContent"
></div>
data-utm-term"adwords"Sets the utm_term parameter that is passed to BallotReady. If any UTM parameters are used, it will overide those actually in the URL<div class="civicengine-address"
data-utm-term="yourUTMTerm"
></div>

Multiple language attributes: data-input-locale and data-default-locale#

If you have translations included in your tool, you can go two different routes with displaying those options in the widget to users. We provide a widget field that allows users to select your supported languages from a dropdown (data-input-locale), and an attribute that translates your entire widget (data-default-locale), including any user data fields in the widget. When users access your site through this widget, your engine will appear by default in the language set in the default. The default language can be specified by language codes, which you'll receive from your contact if you have multiple supported lanugages.

AttributeValue optionsDescriptionExample
data-input-locale"yes"creates language dropdown<div class="civicengine-address"
data-input-locale="yes"
></div>
data-default-locale"es", "zh", "ar"translates widget and site
into default language
(example is default Spanish)
<div class="civicengine-address"
data-input-email="required"
data-default-locale="es"
></div>

  1. Custom field values: contact your Onboarding Manager for details on how to add a list of custom values to your widget, or submit a ticket to our helpdesk. Custom field list is limited to 1000 rows.