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.)

Campaign Customizatons

Promoboxx campaigns can be individually customized by each participating retailer. To enable retailer campaign customizations, create an html file separate from your campaign file. Build a valid html document that contains the Promoboxx JSAPI basic initialization script. The <body> of the document only needs to contain a standard html <form> with standard <input>, <select>, and <textarea> field elements that have unique name attribute values. In the Promoboxx Control Panel, point the customizations url field for the campaign to the hosted location of the file.

The stored customization data can then be used on the consumer-facing campaign page by automatic injection with the pbxx-data-[...] custom content class token or though javascript in the _pbxx.campaign.customzations object.




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

Customization Class Tokens

These special class tokens are available for use in customization forms.

Token Description
pbxx-customization-form

Indicates a campaign retailer customization form. Applies to form elements only.

Example Input
  <form class="pbxx-customization-form">
    <label>Indicate your store's favorite color</label>
    <input name="retailer_favorite_color" />
  </form>      
pbxx-form-repeatable

Indicates that this form element is an array, meaning the user may choose to specify as many versions of this element as desired when filling out the form. This token could be used to create a list or a photo gallery with an unknown number of elements. The controls required to add and remove elements will be automatically applied when the form is rendered.

To indicate that a group of fields should be a repeatable block, group the elements inside of a fieldset with the pbxx-form-repeatable class and a name attribute that associates or "namespaces" the included elements. The fieldset name will then be used to label the array of grouped values in the stored dataset. The fieldset's name must be used as a prefix in the name attribute of each included field and the specific field name should be enclosed in array brackets arrayname[fieldname]. To follow proper "PHP-style" form syntax, you may want to include empty brackets in the fieldset name, though this not neccessary to produce properly structured data arrayname[][fieldname].

Example: Single Element
<input class="pbxx-form-repeatable" name="employee_profile_photo" />
Example: Grouped Elements
  <label>Event Photo Gallery</label>
  <fieldset class="pbxx-form-repeatable" name="gallery_photo">
    <input class="pbxx-customization-image" name="gallery_photo[caption]" />
    <input name="gallery_photo[image]" />
  </fieldset>      
pbxx-customization-image

Indicates that this element should store an image uploaded by the client. This token should only be applied to an <input /> element of type "text." (Do not use type="image.") The controls needed to handle uploading and displaying images will be applied automatically when the form is rendered.

Example
<input type="text" class="pbxx-customization-image" name="storefront_photo" />
pbxx-form-success

Contains content that will be displayed when the form data is saved. This section could contain rendered saved content using pbxx-data-campaign-customizaton-[...] tokens or a simple success message. It is recommended to add a page refresh button to return to editing mode.

Example
<div class="pbxx-form-success">
  <p>Campaign customizations saved!</p>
  <button onclick="document.location.reload(true)" class="pbxx-button">Back to Editing</button>
</div>	

Basic Example

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
  <meta name="viewport" content="width=device-width,initial-scale=1">
</head>
<body>

<form class="pbxx-customization-form">
  <label>Full inventory url with protocol <small>(include http://)</small></label>
  <input type="text" name="inventory_url" class="pbxx-form-validate-url-absolute" title="Full url with protocol" />
  <label>Items available at your store:</label>
  <input type="text" name="available_items" class="pbxx-form-repeatable" />
</form>

<div class="pbxx-form-success">
  <p>Campaign customizations saved!</p>
  <button onclick="document.location.reload(true)" class="pbxx-button">Back to Editing</button>
</div>

</body>
<script>
	var _pbxx = _pbxx || [];
	_pbxx.load('xxxxxxxxxxxx');
</script>
<script src="https://www.promoboxx.com/jsapi/0.6.5/pbxx.js"></script>
</html>

Basic Custom Data Usage Example

<h3>Featured Items:</h3>
<a class="pbxx-data-campaign-customization-inventory_url" data-pbxx-target-attr="href">View our Inventory</a>
<div class="pbxx-data-campaign-customization-available_items"></div>