The current version of the Promoboxx Javascript API is:

0.6.5

Please use the latest API version on new projects to ensure all known bugs are fixed and all documented features are available. See the Initialization chapter for API link code syntax.

(Note: Live projects should be thoroughly tested when upgrading.)

Content Tokens

CSS class tokens allow your html campaign document to become a template for Promoboxx campaign data. Simply create placeholder elements in positions on the page where you would like campaign content inserted and include the appropriate class token in the element's class attribute. Once campaign content is available, the element will be rendered or replaced with appropriate Promoboxx API content. Some tokens will insert simple campaign, retailer, or location data, while others will insert styled widgets of composite data.

See the Quick Start chapter for examples of content token usage.

Token Types

Note: The term “retailer” refers to the currently selected local retailer, dealer, etc.

Campaign Data

Token Description
pbxx-campaign-name

The Campaign name. Note this is retialer-facing and may not be appropriate for the consumer view of the campaign.

Example Input
<b class="pbxx-campaign-name"></b>
Example Output
<b class="pbxx-campaign-name">Awesome Campaign</b>
pbxx-share-buttons

A precomposed block of buttons for sharing this campaign on Facebook and Twitter. Equivalent to using pbxx-share-facebook and pbxx-share-twitter together.

Example Input
<div class="pbxx-share-buttons"></div>
Example Output
<div class="pbxx-share-buttons">
  <button class="pbxx-share-facebook">
    <img src="http://engine.promoboxx.com/jsapi/0.5/pbxx-facebook.png" />
    Post to Facebook
  </button>
  <button class="pbxx-share-twitter">
    <img src="http://engine.promoboxx.com/jsapi/0.5/pbxx-twitter.png" />
    Share on Twitter
  </button>
</div>
pbxx-share-facebook

Adds Facebook sharing functionality to an element, usually a button or link.

Example
<a class="pbxx-share-facebook">Share on Facebook</a>
pbxx-share-twitter

Adds Twitter sharing functionality to an element, usually a button or link.

Example
<a class="pbxx-share-twitter">Tweet</a>

Brand Data

Token Description
pbxx-brand-name

The brand’s name.

Example Input
<b class="pbxx-brand-name"></b>
Example Output
<b class="pbxx-brand-name">Acme Co.</b>
pbxx-brand-website

The brand’s website. Used with the a element only. Sets the href attribute automatically. If there is no text content, the text will be set to the same URL as the href.

Example Input
<a class="pbxx-brand-website">Acme Co.</a>
Example Output
<a class="pbxx-brand-website" href="http://www.acme.example">Acme Co.</a>
Example Input
<a class="pbxx-brand-website"></a>
Example Output
<a class="pbxx-brand-website" href="http://www.acme.example">http://www.acme.example</a>
pbxx-brand-twitter

Inserts the brands's twitter handle (including "@" prefix). If the element is an <a> tag, it will be linked to the brand’s twitter page.

Example
<div class="pbxx-retailer-twitter"></div>
pbxx-brand-twitter-follow

Applies "twitter follow button" functionality to an <a> element, linking it to the brand’s twitter page.

You may add optional "data" attributes to modify the style of the button. (See the Twitter button documentation for available attributes.)

Example
<div class="pbxx-brand-twitter-follow" data-show-count="false" data-size="large"></div>
pbxx-brand-like-button

A “Like” button for the brand’s Facebook Page. Rendered as an iframe via the Facebook SDK.

pbxx-brand-like-box

A precomposed block containing a link to the brand’s Facebook page, with name, logo, and a “Like” button. Rendered as an iframe via the Facebook SDK.

Note: add the data-width attribute to an element with this token to control the width of the resulting content. This can be helpful when used on elements within a narrow column.

Example With Data-Width Attribute
<div class="pbxx-brand-like-box" data-width="220"></div>
pbxx-brand-like-box-custom

A precomposed block containing a link to the brand’s Facebook page, with name, logo, and a “Like” button. Rendered as within-document HTML that can be custom-styled. (See pbxx-local-like-box-custom for an example of output)

*Note that for age-gated Facebook sites (e.g., alcoholic beverage brands and retailers), the profile image box will always display a question mark when using this control. It is not recommended to use this version of the like-box token for brands with age-gate considerations.

pbxx-retailer-alias

If a "retailer alias" has been specified for this brand in the Promoboxx Control Panel, (e.g. “dealer”, “merchant”, “vendor”, etc.), that term will be injected into elements with this token.

Example Input
<p>Find your nearest Acme <span class="pbxx-retailer-alias"></span>:</p>
Example Output
<p>Find your nearest Acme <span class="pbxx-retailer-alias">dealer</span>:</p>

Local (Retailer) Data

Token Description
pbxx-local-block

A precomposed block displaying basic information for the loaded retailer. This may include any of the following (depending on available data): Name, logo, address, phone, website, location map, and a Facebook Like box (if not specified elsewhere).

Example Input
<div class="pbxx-local-block"></div>
Example Output
<div class="pbxx-local-block">
  <h3 class="pbxx-local-name">Bob’s Store</h3>
  <div class="pbxx-local-address">
    123 Main Street<br />
    Apt. 1A<br />
    Anywhere, AZ 01234
  </div>
</div>
pbxx-local-name

The retailer’s name.

Example Input
<b class="pbxx-local-name"></b>
Example Output
<b class="pbxx-local-name">Bob’s Store</b>
pbxx-local-address

A precomposed block displaying the full address for the retailer. Equivalent to using Street Address (not exposed separately), pbxx-local-city, pbxx-local-state, and pbxx-local-zip together.

Example Input
<div class="pbxx-local-address"></div>
Example Output
<div class="pbxx-local-address">
  123 Main Street<br />
  Apt. 1A<br />
  Anywhere, AZ 01234
</div>
pbxx-local-city

City or locality for the retailer.

Example Input
<span class="pbxx-local-city"></span>
Example Output
<span class="pbxx-local-city">Anywhere</span>
pbxx-local-state

Abbreviated state or region for the retailer.

Example Input
<abbr class="pbxx-local-state"></abbr>
Example Output
<abbr class="pbxx-local-state">MA</abbr>
pbxx-local-zip

ZIP or postal code for the retailer.

Example Input
<span class="pbxx-local-zip"></span>
Example Output
<span class="pbxx-local-zip">01234</span>
pbxx-local-map

A Google Map displaying the location of the retailer. pbxx-loaded will be appended as an additional class after it is done rendering.

Example Input
<div class="pbxx-local-map"></div>
Example Output
<div class="pbxx-map pbxx-loaded" style="width: 100%; position: relative; background-color: rgb(229, 227, 223); overflow: hidden; -webkit-transform: translateZ(0);">
    <!-- Google Maps code -->
</div>
pbxx-local-phone

The retailer’s phone number, formatted for readability.

Example Input
<span class="pbxx-local-phone"></span>
Example Output
<span class="pbxx-local-phone">(555) 123-4567</span>
pbxx-local-website

The retailer’s website. Used with the a element only. Sets the href attribute automatically. If there is no text content, the text will be set to the same URL as the href.

Example Input
<a class="pbxx-local-website">Bob’s Store</a>
Example Output
<a class="pbxx-local-website" href="http://www.bobs-store.example">Bob’s Store</a>
Example Input
<a class="pbxx-local-website"></a>
Example Output
<a class="pbxx-local-website" href="http://www.bobs-store.example">http://www.bobs-store.example</a>
pbxx-local-other-locations

If the retailer has more than one location, displays the other locations apart from the one selected, each in the same format as pbxx-local-address.

pbxx-retailer-twitter

Inserts the retailer's twitter handle (including "@" prefix). If the element is an <a> tag, it will be linked to the retailer’s twitter page.

Example
<div class="pbxx-retailer-twitter"></div>
pbxx-retailer-twitter-follow

Applies "twitter follow button" functionality to an <a> element, linking it to the retailer’s twitter page.

You may add optional "data" attributes to modify the style of the button. (See the Twitter button documentation for available attributes.)

Example
<div class="pbxx-retailer-twitter-follow" data-show-count="false" data-size="large"></div>
pbxx-local-like-button

A “Like” button. Rendered as an iframe via the Facebook SDK.

pbxx-local-like-box

A precomposed block containing a link to the retailer’s Facebook Page, with name, logo, and a “Like” button. Rendered as an iframe via the Facebook SDK.

Note: add the data-width attribute to an element with this token to control the width of the resulting content. This can be helpful when used on elements within a narrow column.

Example With Data-Width Attribute
<div class="pbxx-local-like-box" data-width="220"></div>
pbxx-local-like-box-custom

A precomposed block containing a link to the retailer’s Facebook page, with name, logo, and a “Like” button. Rendered as within-document HTML that can be custom-styled.

*Note that for age-gated Facebook sites (e.g., alcoholic beverage brands and retailers), the profile image box will always display a question mark when using this control. It is not recommended to use this version of the like-box token for brands with age-gate considerations.

Example Input
<div class="pbxx-local-like-box-custom"></div>
Example Output
<div class="pbxx-local-like-box-custom pbxx-loaded pbxx-like-box-custom">
  <a href="http://facebook.com/promoboxx" target="_blank">
    <img src="http://graph.facebook.com/promoboxx/picture" />
    <p>
      Bob’s Store
      <span class="fb-like fb_edge_widget_with_comment fb_iframe_widget" data-href="http://facebook.com/promoboxx" data-send="false" data-layout="button_count" data-width="120" data-show-faces="false" data-font="lucida grande" fb-xfbml-state="rendered">
        <span style="height: 20px; width: 84px;">
          <iframe id="f255654a1" name="f38c9a7794" scrolling="no" style="border: none; overflow: hidden; height: 20px; width: 84px;" title="Like this content on Facebook." class="fb_ltr" src="http://www.facebook.com/plugins/like.php"></iframe>
        </span>
      </span>
    </p>
  </a>
</div>

Forms

Token Description
pbxx-form

Indicates a form that should be handled by the API.

* pbxx-loaded will be appended as a class after campaign content has loaded.

pbxx-form-errors

A container for reporting form errors. If missing (and an element with pbxx-form is present), a container will be created and added to the top of the pbxx-form element during loading.

Before Validation
<div class="pbxx-form-errors" style="display:none;"></div>
After Failed Validation
<div class="pbxx-form-errors" style="">
  <p class="pbxx-form-error-title">Please correct the following errors:</p>
  <ul>
    <li>Name is required</li>
    <li>Email address with domain is required</li>
    <li>Check1 is required</li>
    <li>Radio1 is required</li>
    <li>Select1</li>
  </ul>
</div>
pbxx-form-required

Indicates that a form field is required. May be used in addition to, or instead of, the HTML required attribute.

Example
<input class="pbxx-form-required" name="name" type="text" required="required" />
The title attribute (or otherwise the name attribute), will be used to build validation error messages.
pbxx-form-submit

A submit button for a form. If missing (and an element with pbxx-form is present), a button will be created with this class for submitting the form

Example
<button class="pbxx-form-submit">Submit</button>
pbxx-form-success

A success message to be displayed when a form has been submitted and passed validation, whereupon it replaces the form itself.

Before Validation
<form class="pbxx-form pbxx-loaded">
  <div class="pbxx-form-errors" style="display:none;">
  <label>Name: <input type="text" name="name" /></label>
  <div class="pbxx-form-success" style="display:none;">
    Success!
  </div>
</form>
After Passed Validation
<div class="pbxx-form-success" style="">
  Success!
</form>
pbxx-form-validate-email

Indicates that a form field should contain a valid e-mail address.

Example
<input class="pbxx-form-validate-email pbxx-form-required" name="email" type="email" title="E-mail address with domain" />
The title attribute (or otherwise the name attribute), will be used to build validation error messages.
pbxx-form-validate-phone

Indicates that a form field should contain a valid phone number. Location data, if present, is taken into account during validation.

Example
<input class="pbxx-form-validate-phone pbxx-form-required" name="tel" type="tel" />
The title attribute (or otherwise the name attribute), will be used to build validation error messages.

Retailer Lookup (For Brand View)

Token Description
pbxx-retailers-map

A Google Map displaying the location of more than one retailer, so that the user may choose one for localization purposes. Includes pbxx-map-empty, pbxx-map-canvas, pbxx-map-lookup, pbxx-map-searching, and pbxx-map-loading as child divs. pbxx-loaded will be appended as an additional class after it is done rendering.

Example Input
<div class="pbxx-retailers-map"></div>
Example Output
<div class="pbxx-map-select pbxx-loaded" style="width:500px;">
  <div class="pbxx-map-empty">
    Please enter your location above to continue.
  </div>
  <div class="pbxx-map-canvas" style="background-color: rgb(229, 227, 223); overflow: hidden; -webkit-transform: translateZ(0); visibility: visible;">
    <!-- Google Maps code -->
  </div>
  <div class="pbxx-map-lookup">
    <label class="pbxx-map-lookup-label">Enter your zip code or city</label><input class="pbxx-map-lookup-input" placeholder="Zip / City"><span class="pbxx-map-lookup-submit">&gt;</span>
  </div>
  <div class="pbxx-map-searching" style="visibility: hidden;"></div>
  <div class="pbxx-map-loading" style="visibility: hidden;">
    Updating
  </div>
</div>
pbxx-retailers-list

A list of all of the associated retailers for the current brand. Populates when a pbxx-map-lookup completes.

Before Lookup
<div class="pbxx-retailers-list"></div>
After Lookup
<div class="pbxx-retailers-list pbxx-loaded">
  <ul>
    <li>
      <a href="./?15500/21216">ATP Boxxer</a>
      <button class="pbxx-retailers-list-mapit" id="loc21216">map</button>
    </li>
    <li>
      <a href="./?1831/384">dan 2</a>
      <button class="pbxx-retailers-list-mapit" id="loc384">map</button>
    </li>
  </ul>
</div>

Wildcard Data

Token Description
pbxx-data-[...]

Using this wildcard format, any piece of data available in the _pbxx object can be written into the page automatically. Refer to Campaign Data for specifics on available data. Simply append the object reference to the _pbxx-data- prefix, separating child objects with dashes instead of periods.

To write the retrieved data to an element attribute instead of the element' html, indicate the attribute by adding the data-pbxx-target-attr to the element tag.

Examples
<div class="pbxx-data-brand-name"></div>

(Output is identical to the pbxx-brand-name token)


<a class="pbxx-data-retailer-facebook_url" data-pbxx-target-attr="href">Check us out on Facebook</a>

Retailer Engagement

Token Description
pbxx-xengage

Makes an element a trigger to open a popup contact form for potential retailers interested in contacting Promoboxx about joining this campaign. This is a way to capture retailers that have become interested in participating after seeing your campaign on another retailer’s site. This element is usually included in the footer of the campaign page.

Example
<div class="pbxx-xengage">Participate in this campaign »</div>