Dev-in-a-Box Documentation
Dev-in-a-Box is a jQuery plugin designed to simplify the most common JavaScript features in Business Catalyst site development. It is easily the most powerful plugin designed for Business Catalyst, and it continues to become even better.
Dev-in-a-Box has a number of tricks, or widgets, that are controlled entirely with HTML5 data attributes. Data attributes might sound scary, but there is really very little you need to learn about them. A data attribute is used just like any other attribute you would add to an HTML element. If you can add a class or id, you can work with data attributes.
<nav id="topnav" data-bc-activenav="true">...</nav>
Why data attributes? For productivity. It's much faster to add a data attribute to your HTML than it is to write, or even implement, JavaScript. In fact, the data attribute in the example above is enough to implement ActiveNav on a menu. Also, using data attributes keeps us from muddying up your HTML with extra classes, which would cause clutter and confusion. Though, as needed in my own development, I do add classes and IDs to elements for scripting, as much as possible I like to leave classes for styling. So Dev-in-a-Box is built with that in mind.
Getting Started
Preparation
Install (or verify that you have) jQuery 1.8.3+
Verify that jQuery exists somewhere in your document. It should be placed somewhere before Dev-in-a-Box, not after. Also, Dev-in-a-Box has not been tested on versions of jQuery lower than 1.8.3. I advise upgrading your copy of jQuery if it is older than that.
Installation
Download
Download Dev-in-a-Box and upload either devinabox.js (uncompressed developer’s copy) or devinabox.min.js (compressed, recommended for live sites) to your website.

Dev-in-a-Box can be purchased on the BC App Store, and anytime afterwards redownloaded from there. Or, if you register your purchase on this website (create a free account, then go to your product registration page inside your account area), you can download an early release version from here.
Copy and Paste
Copy the following snippet and add it to the foot of your page templates, just before the closing body tag. This snippet includes the reference to the devinabox.js script.
<div id="bcmodules" style="display:none;"
data-bc-pagename="{module_pagename}"
data-bc-pageaddress="{module_pageaddress}"
data-bc-sitehost="{module_sitehost}"
data-bc-siteurl="{module_siteurl}"
data-bc-secureurl="{module_secureurl}"
data-bc-loginstatus="{module_isloggedin}"
></div>
<script src="/scripts/devinabox.js"></script>
Update the Snippet
Update the src location of the script element to match the location where you uploaded the file.
Key Usage Concepts
Data attributes
No need to write JavaScript. Dev-in-a-Box tricks are called through HTML5 data attributes. Data attributes ae like other HTML attributes, with a few exceptions:
- All data attributes start with data and are followed by a custom attribute name.
- A - separates the different parts of the name.
- Data attributes' values are readily accessible to scripts, making them more efficient to code with.
- Coders can store and access values in data attributes like they would with a variable, making them more useful for scripting than an ID or class.
Calling a trick
Dev-in-a-Box tricks are differentiated from other data attributes by adding the namespace bc- between the data- and the rest of the attribute name. Each trick has its own data attribute, following this pattern:
<div data-bc-trickname>...</div>
In most cases, simply adding an attribute to an element, without specifying any options, is sufficient to call a trick. In these scenarios, the trick will work immediately, using the default option values. Some tricks, however, require an option to be specified before they will do anything.
If you do not specify any options for a trick, assign it a value of “true”. This will prevent the Business Catalyst admin interface from deleting it. This is best practice in BC, as Business Catalyst's interface doesn't recognize HTML5 markup patterns, and deletes attributes that don't have values assigned.
<div data-bc-trickname="true">...</div>
If you are not planning to change an option from its default value, there is no need to declare the option. Undeclared options will automatically work with their default value.
Dev-in-a-Box tricks only apply to the elements they are placed on and their children. Beyond that, the documentation for each trick will give you instructions for where and how it can be used.
Options syntax
<div data-bc-trickname="option1: value; option2: value;">...</div>
Options are written with a CSS-style syntax in the value portion of the data attribute (the red area above). Here are the key points to keep in mind:
- Options are separated by a ; (semicolon)
- Leading or trailing spaces are ignored (so option1: value; option2: value; is the same as option1:value;option2:value;
- A : (colon) is used to separate an option name from its value. However, you are free to use them in your values. Dev-in-a-Box defines the value as everything between the first : (colon) following an option name, and the ; (semicolon). So, option1::::; (four colons) is read as having a value of ::: (three colons).
There are only two reserved characters in the option syntax. These have express meaning to the plugin or HTML itself:
- A ; (semicolon) is used to separate additional options from the values of the options that precede them. This is the same as CSS, where a rule might have color:red; text-decoration: underline.
- A " (double quote) is used by HTML to surround the data attribute value, so cannot be used at all in the options.
Special Circumstances
Occasionally, in order to accomplish certain functionality, it will be necessary to add a special data attribute somewhere on your site. This is extremely rare, and will always be noted in the individual trick’s documentation.
Troubleshooting
Keeping your site clean is the best form of prevention. Troubleshooting will always be easier if you follow best practices in coding.
If you need help, I am happy to come to the rescue. Please report bugs or questions to adam@onecreative.pro.
Versions
When troubleshooting issues, it can be helpful to check which version of a trick you are using. Dev-in-a-Box doesn't have a version number for the entire plugin, just a release date. However, it does have version numbers for each of its parts, including its engine and each of its tricks.
On this documentation page, version numbers are listed next the trick names. You can check the versions of the tricks installed on your site by opening up the developer tools in your browser, and then in the console writing $.bcEngine() and hitting enter. The console will then return an object with the version numbers for each part. Depending on the browser you are using, you should simply be able to click on that object to view the versions.
License
Dev-in-a-Box is licensed on a per-partner basis. A "partner" is considered a person or company who has a Business Catalyst partner portal. A single Dev-in-a-Box license can be used on an unlimited number of sites, as long as those sites are being built for a licensed partner. So contractors and production houses who own a copy of Dev-in-a-Box are only free to add the plugin to their own sites and to sites for partners who have their own license of the plugin.
Updates to Dev-in-a-Box, both big and small, are always free.
Crumbs (2.1.0)
Crumbs is a full replacement for the breadcrumbs modules in Business Catalyst. BC’s breadcrumbs modules are inconsistent, require specific placement, and depend on you manually defining them with the sitemap module. Crumbs, on the other hand, are always accurate, can be placed anywhere on your site, and intelligently name your breadcrumbs based on your actual page names. You'll never look back.
Usage
Topic | Usage |
---|---|
Data Attribute | data-bc-crumbs |
Placement | On any empty element. Crumbs will be added inside. |
Required Options | None. |
Options
Option | Default Value | Notes |
---|---|---|
separator | / | Defines the character(s) that separates each breadcrumb. (eg, home / shop / widget) |
makespace | - | When the pagename cannot be discovered with Ajax, Crumbs creates the breadcrumb by dissecting the URL. This option defines which character(s) in the URL will be replaced with a space. |
showHome | false | Determines whether or not the breadcrumbs will begin with Home/. |
homeTitle | Home | If showHome is set to true, you can specify the title of that crumb with this option. |
Examples
<div></div>
Without options
With no options specified, Crumbs uses all its default settings.
<div data-bc-crumbs="true"></div>
Changing the separator
Here, we change the separator from / to ».
<div data-bc-crumbs="separator:»"></div>
Date (2.3.0)
Date is a powerful way to display custom-formatted date and time information anywhere on your site. It harnesses the functionality of moment.js, while maintaining the simplicity of Dev-in-a-Box.
Usage
Topic | Usage |
---|---|
Data Attribute | data-bc-date |
Placement | On any empty element. Date will add its contents inside the element. |
Required Options | None. |
Options
Option | Default Value | Notes |
---|---|---|
format | YYYY | Syntax for format can be found on http://momentjs.com/docs/#/displaying/format/. Anything inside the parenthesis of .format() can be used, with the exception of single and double quotes. Single quotes are not necessary in Dev-in-a-Box, and double quotes are specifically reserved for opening and closing HTML attributes. |
add | ||
subtract | ||
moment | auto | Should match the format of your inputted date/time string. The default value is based on BC's standard date formatting. The default value, 'auto', tries to guess your formatting. It's usually right on. |
event | load | specify the event that triggers Date's behavior. The default, 'load', trigger's date on page-load. You can specify any event recognized by jQuery, including 'change' and 'keyup', which are the most useful alternates to 'load'. |
ref | text | specify an html attribute to reference for date/time information. Default is text (inputs will default to 'value'), meaning Date will look at the text inside the element. To reference the current date and time, set the value to 'now'. |
target | text | Specify an html attribute to receive the outputted date/time information. Default is text (inputs will default to 'value'), which means Date will replace any text inside the element with the new date/time info. Separate multiple targets with commas. |
Examples
Without options
Without any options specified, and placed on an empty html element, Date outputs the current year in four digit format.
<span data-bc-date="true"></span>
format
You can apply custom formatting to the date by using the format option.
<span data-bc-date="format:MMM DD, YYYY"></span>
add
With the add option, you can display a date in the future. In this example, we are also using format so you can see that add can be used for more than just years.
<span data-bc-date="format: MMM DD, YYYY; add: years:1,months:6,days:3"></span>
subtract
The subtract option is the opposite of add.
<span data-bc-date="format: MMM DD, YYYY @ha; subtract: days:6,years:2,hours:4"></span>
FormMagic (2.1.5)
FormMagic takes all the headache out of working with forms in BC. Feel free to get rid of the clutter BC automatically adds to your forms. You can delete the JavaScript and strip your forms down to their skivvies, and rest assured they will work even better than they did before. Enhanced validation and easy Ajax are the hallmarks of this amazing trick.
Usage
Topic | Usage |
---|---|
Data Attribute | data-bc-formmagic |
Placement | Form element. |
Required Options | None. |
Options
Option | Default Value | Notes |
---|---|---|
requiredClass | required | The name of the class FormMagic looks for when determining the required fields. |
errorGroupElement | div | The element type that surrounds a required input after it fails validation. This element is created and removed dynamically. |
errorGroupClass | error-group | The name of the class applied to the errorGroupElement. |
errorMessageElement | small | The element type that contains the error message after a required input fails validation. This element is created and removed dynamically. |
errorClass | error | The name of the class applied to the errorMessageElement and the required input after failed validation. |
messageBoxID | bcmodules | The ID of the element used to receive the message after a successful Ajax submission. This works in conjuction with messageMode. |
messageMode | prepend | append, box; Decides where the message box will be displayed after an Ajax submission. Prepend places the message box directly before the form, append places it directly after, and box simply adds it to the location identified by MessageBoxID without moving it. |
afterAjax | remove | hide, show Determines what to do with the form after receiving an Ajax response message. |
useAjax | false | Determine if the form should be submitted through Ajax. |
validateMode | alert | The method used to show errors for invalid fields. alert is a standard browser alert box, while inline shows the errors next to the invalid fields. Note: Currently, for radio and checkboxes, FormMagic will only attach an error message/class to an associated label element. For it to work, it needs to be written like <label for="[input name]"... |
fieldTitleAttr | label | or specify a field attribute |
systemMessageClass | system-message | The name of the class applied to the element surrounding the submission success message. This message is retrieved via Ajax from /Layouts/SystemMessages/FormConfirmation-[your site’s country code].html |
systemErrorMessageClass | system-error-message | The name of the class applied to the element surround the submission error message. This message is retrieved via Ajax from /Layouts/SystemMessages/General-[your site’s country code].html |
successClass | success | |
submitEvent | null | keyup, onblur; Submits the form after a specified event. For instance, keyup or onblur for a specified field. Great for ajax live searches (like Google). |
submitField | [type="submit"] | Takes a CSS selector. submitField allows you to assign another field to submit the form. Works in conjunction with submitEvent. |
noSubmit | false | Prevents submission of the form. |
ajaxError | null | specify a function to run after an Ajax submission 'error' response |
ajaxSuccess | null | specify a function to run after an Ajax submission 'success' response |
ajaxComplete | null | specify a function to run after an Ajax submission 'complete' response |
multistep | false | True if this is a multistep form or validations are to be done in steps |
containers | multistep container selectors, separated by comma | |
continueButton | Continue button selector for multi step form | |
backButton | back button selector for multi step form | |
buttonAfterSubmit | enable | Determines what to do with the submit button after a form submission completes. Possible values are none, enable, hide, show, disable. |
buttonOnSubmit | disable | Determines what to do with the submit button while a form submission is in progress. Options are none, disable, or hide. |
restoreMessageBox | true | If an ajax submission result is empty, the original contents of messageBox will be restored. This is particularly helpful with live searches. |
validationError | null | Specify a function to run after validation returns errors on submit. |
validationSuccess | null | Specify a function to run after validation, but before submission. |
Examples
This is a very basic BC form. I've reduced it down to its bare necessities, and then wrapped the inputs in label elements (for styling purposes). The only thing I did that was required for FormMagic to work is remove the onSubmit attribute from the form element.
I should note that the forms below don't actually submit correctly. That was on purpose. I figured it would be better than muddying up my CRM with hundreds of fake contacts and form submissions.
Without Options
If you don't specify any options, FormMagic will handle the form exactly the way BC's native JavaScript would. FormMagic does need class="required" on fields you want to require, although there is no need to add that class to the following fields, as they are always required:
- FirstName
- LastName
- FullName
- EmailAddress
- CaptchaV2
- ItemName
A few other fields are auto-required, but conditionally. For instance, the following are only required when Credit Card is selected as the payment method type in the form:
- CardName
- CardNumber
- CardExpiryMonth
- CardExpiryYear
- CardType
- CardCCV
The following form has no options specified, and does exactly what you would expect a Business Catalyst form to do (except that I gave it a fake WebFormID to make the submission fail).
<form data-bc-formmagic="true" enctype="multipart/form-data" action="/FormProcessv2.aspx?WebFormID=123456&OID=15705642&OTYPE=1&EID=0&CID=0">
<label>First Name
<input type="text" name="FirstName">
</label>
<label>Last Name
<input type="text" name="LastName">
</label>
<label>Email Address
<input type="email" name="EmailAddress">
</label>
<label>Message
<textarea name="CAT_Custom_523434"></textarea>
</label>
<label>Enter Word Verification in box below
{module_captchav2}
</label>
<input class="small button" type="submit" value="Submit">
</form>
Inline Validation
With validateMode:inline specified, FormMagic will show validation errors next to the invalid fields. We've also used useAjax:true to allow the form to submit without a page refresh.
<form data-bc-formmagic="validateMode:inline;useAjax:true" enctype="multipart/form-data" action="/FormProcessv2.aspx?WebFormID=123456&OID=15705642&OTYPE=1&EID=0&CID=0">
<label>First Name
<input type="text" name="FirstName">
</label>
<label>Last Name
<input type="text" name="LastName">
</label>
<label>Email Address
<input type="email" name="EmailAddress">
</label>
<label>Message
<textarea name="CAT_Custom_523434"></textarea>
</label>
<label>Enter Word Verification in box below
{module_captchav2}
</label>
<input class="small button" type="submit" value="Submit">
</form>
Multistep Form
With FormMagic, you can add amazing features to your forms, making them as simple or complex as you want. In this example, we've added a few fields and added FormMagic's multistep:true options as well. We've also required a few extra fields.
multistep breaks your form validation up into, well, multiple steps. It won't allow continuing to the next step until validation for the current step is passed.
Be sure to put only one of each button, and keep them outside of your containers!
<form data-bc-formmagic="validateMode:inline; useAjax:true; multistep:true; containers:#formStep1,#formStep2; continueButton:#btnContinue; backButton:#btnBack;" enctype="multipart/form-data" action="/FormProcessv2.aspx?WebFormID=123456&OID=15705642&OTYPE=1&EID=0&CID=0">
<div id="formStep1">
<label>First Name
<input type="text" name="FirstName">
</label>
<label>Last Name
<input type="text" name="LastName">
</label>
<label>Email Address
<input type="email" name="EmailAddress">
</label>
<label>Message
<textarea name="CAT_Custom_523434"></textarea>
</label>
</div>
<div id="formStep2">
<label>Home Address
<input type="text" name="HomeAddress" class="required">
</label>
<label>City
<input type="text" name="HomeCity" class="required">
</label>
<label>State
<input type="text" name="HomeState" class="required">
</label>
<label>Zipcode/Postcode
<input type="text" name="HomeZip" class="required">
</label>
<label>Country
<select name="HomeCountry" class="required">
<option value="US">United States</option>
<option value="CA">Cananda</option>
<option value="UK">United Kingdom</option>
<option value="AU">Australia</option>
</select>
</label>
<label>Enter Word Verification in box below
{module_captchav2}
</label>
</div>
<input class="small button" type="button" value="Continue" id="btnContinue">
<input class="small button" type="button" value="Back" id="btnBack">
<input class="small button" type="submit" value="Submit">
</form>
SameAs (2.2.1)
For those times when you need to copy one field's value to another, SameAs has your back. It even allows you to setup copy groups, like billing and shipping fields, or do math with the field values. It’s easy syntax simply could not be faster to implement.
Usage
Topic | Usage |
---|---|
Data Attribute | data-bc-sameas |
Placement | On any input, select, or textarea element. |
Required Options | copy |
Options
Option | Default Value | Notes |
---|---|---|
copy | Required. Specifies the field whose value will be copied. | |
bothWays | false | Determines whether the two fields’ values will match, regardless of which field’s value is altered. |
checkbox | The name of the checkbox that copying should depend on. When the checkbox is checked, the value will be copied. When it is unchecked, the value will be cleared. You can make any number of fields dependent on the same checkbox. This allows groups of fields to be controlled by a single checkbox. | |
clearOnUncheck | true | Determines whether or not copied values will be cleared when the checkbox is unchecked. This option is dependent on the checkbox option being set. |
attributeType | name | Allows you to specify the html attribute type SameAs references in its 'copy' option. |
breakOnChange | false | Breaks the SameAs link between the source and destination field if the source field value is changed. Requires bothWays:false. |
copyType | simple | Determines what type of syntax/functionality is possible with the 'copy' option. Possible values are simple, concat, and math. simple allows a syntax of copy:fieldName;, and simply copies the source field value to the destination field. concat allows a syntax of copy:[fieldName1] some additional text [fieldName2]+[fieldName3];, and treats text inside square brackets ([ ]) as field names, and everything else as text. The resulting value is a concatenation of them all. math allows a syntax of copy:[fieldName1] * ([fieldName2]+[fieldName3]) / 4;, and treats text inside square brackets ([ ]) as field names, and everything else as numbers and mathematical operators. Math recognizes order of operations. If the equation can be evaluated, the result will be placed, otherwise it will revert to concat. |
event | change | specify the event that triggers the copy. |
prefiix | Prepends the copied value with a specified string of characters. | |
ref | value | or text. |
scope | form | Uses 'form' or css selectors as values. This allows for setting a larger or smaller scope for SameAs as it searches for a source field. |
suffix | Prepends the copied value with a specified string of characters. |
Examples
SameAs requires you to specify a value for the copy option.
The value should be the name of a field you want to copy from.
<input type="text" name="Username" data-bc-sameas="copy:EmailAddress"></div>
With a checkbox
You can make the functionality dependend on a checkbox being checked, and you can tie as many fields to that same checkbox as you want.
<fieldset>
<legend>Billing</legend>
<label>Address<input type="text" name="BillingAddress" data-bc-sameas="copy:ShippingAddress; checkbox:myCheckbox"></label>
<label>City<input type="text" name="BillingCity" data-bc-sameas="copy:ShippingCity; checkbox:myCheckbox"></label>
<label>State/Province<input type="text" name="BillingState" data-bc-sameas="copy:ShippingState; checkbox:myCheckbox"></label>
<label>Zip<input type="text" name="BillingZip" data-bc-sameas="copy:ShippingZip; checkbox:myCheckbox"></label>
<label>Country
<select name="BillingCountry" data-bc-sameas="copy:ShippingCountry; checkbox:myCheckbox">
<option value="US">United States</option>
<option value="CA">Cananda</option>
<option value="UK">United Kingdom</option>
<option value="AU">Australia</option>
</select>
</label>
</fieldset>
Secure (1.0.1)
Make BC's security features work for your site, not against it. Secure can guide users back to your primary domain after performing a transaction on the worldsecuresystems secure domain. Or it can run a custom script, or even redirect a user out of a secure area, when the system automatically logs them out.
Usage
Topic | Usage |
---|---|
Data Attribute | data-bc-secure |
Placement | On any element. Most practical on the body element. UnSecure affects all the child elements of the element it is placed on. |
Required Options | N/A |
Options
Option | Default Value | Notes |
---|---|---|
onSessionEnd | Allows a custom script to be called when Secure discovers that a user has automatically been logged out of the front-end. Syntax is: onSessionEnd:myScript;, where myScript is replaced by the name of your custom script. | |
sessionEndRedirect | Allows you to specify a path that the user will be redirected to when the system automatically logs a user out of the front-end. | |
unsecureLinks | true | When set to true (default), when on the secure domain (worldsecuresystems.com), links within the element will be converted to absolute urls, pointing to the site's standard (insecure) domain. |
Examples
UnSecure may not have any options, but it's incredibly useful. And it just works. It finds all the links on the page, regardless of where they are. Even here.
Without options
Secure can be placed anywhere, but it only affects children of the element it's placed on, so it would generally make sense to place it on the body element.
<body data-bc-secure="true">
<body data-bc-secure="true">
<ul>
<li><a href="http://onecreative.pro/">Home</a></li>
<li><a href="http://onecreative.pro/products">Products</a></li>
<li><a href="http://onecreative.pro/contact">Contact Us</a></li>
</ul>
<article>Secure may not have any options, but it's incredibly useful. And it just works. It finds all the links on the page, regardless of where they are. Even <a href="http://onecreative.pro/here">here</a>.</article>
</body>
Trigger (1.0.1)
Trigger gives you the ability to use one element to 'trigger' a behavior on another. For instance, you may want to add or remove a class when a button is clicked.
Usage
Topic | Usage |
---|---|
Data Attribute | data-bc-trigger |
Placement | On a target element. |
Required Options | At least one of the following: onClass, offClass, onCallback, or offCallback. |
Options
Option | Default Value | Notes |
---|---|---|
event | click | The event that will trigger the trick's behavior. Any jQuery event can be used here. |
trigger | self | Specify the element that will act as the trigger. |
triggerValue | Dependent on event:change. The input, select, or textarea value that sets the trigger to 'on'. If this option is not specified, the trigger will occur on any value change. | |
toggle | false | When set to true, the first event will put the trigger in an 'on' state, and the next event will put it in an 'off' state. When the data attribute is placed on an input, select, or textarea element, this value is always true. |
onClass | The class that will be added to the target element when the trigger is set to 'on'. | |
offClass | Dependent on toggle:true. The class that will be added to the target element when the trigger is set to 'off'. This will also remove the onClass from the target element. If this option is not specified, the onClass will simply be toggled off. | |
onCallback | Specifies a function to execute after a trigger is set to 'on'. | |
offCallback | Dependent on toggle:true. Specifies a function to execute after a trigger is set to 'off'. |
Examples
Below are the styles and custom scripts that Trigger will use in the following examples.
<style type="text/css">
.highlight{
background-color: #2E9AC8;
color: #fff;
}
.defaultStyle{
background-color: inherit;
color: inherit;
}
</style>
<script type="text/javascript">
function callMeOn () {
alert("Hello from CallMeOn");
}
function callMeOff () {
alert("Hello from callMeOff");
}
</script>
Minimal options
Minimal options, speciy just onClass, the trigger and target will be element itself, the class will be applied on click(default event).
<input data-bc-trigger="onClass:highlight;" type="button" value="Click me" >
Different Trigger with toggle(on/off)
Different trigger specified with onClass, offClass and toggle
<input type="button" value="Click me" id="btnTriggerExample1" >
<div data-bc-trigger="onClass:highlight; trigger:#btnTriggerExample1; toggle:true; offClass:defaultStyle;">Hey there!</div>
Self Trigger with toggle classes and callbacks
Callbacks will be executed at on and off events
<input data-bc-trigger="onClass:highlight; offClass:defaultStyle; toggle:true; onCallback:callMeOn; offCallback: callMeOff;" type="button" value="Click me" />
More Advanced Example(Using data value)
Using data values for on and off events will be effective if change event is chosen. Toggle will be true in this case by default.
<select id="triggerExampleDDL" data-bc-trigger="onClass:defaultStyle; offClass:highlight;event:change; triggerValue:select;" style="color:#000;">
<option value="select">Please select</option>
<option value="male">Male</option>
<option value="female">Female</option>
</select>