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.

ActiveNav (2.2.2)

ActiveNav makes it easy to create truly dynamic navigation throughout your site. It can be used to produce something as simple as a highlighted menu item when it represents the current page, to side navigation that only shows links related to the current section of your website.

Goto:

Usage

Options

Examples

Usage

Options

Examples

For the following examples, assume the current url path is /animals/mammals, and that the navigation is built like this:

<nav>
	<ul>
		<li><a href="/animals">Animals</a>
			<ul>
				<li><a href="/animals/mammals">Mammals</a>
					<ul>
						<li><a href="/animals/mammals/land-mammals">Land Mammals</a></li>
						<li><a href="/animals/mammals/marine-mammals">Marine Mammals</a></li>
					</ul>
				</li>
				<li><a href="/animals/reptiles">Reptiles</a>
					<ul>
						<li><a href="/animals/reptiles/crocodiles">Crocodiles</a></li>
					</ul>
				</li>
			</ul>
		</li>
		<li><a href="/vegetables">Vegetables</a>
			<ul>
				<li><a href="/vegetables/roots">Roots</a>
					<ul>
						<li><a href="/vegetables/roots/carrots">Carrots</a></li>
						<li><a href="/vegetables/roots/parsnips">Parsnips</a></li>
					</ul>
				</li>
				<li><a href="/vegetables/bulbs">Bulbs</a>
					<ul>
						<li><a href="/vegetables/bulbs/garlic">Garlic</a></li>
						<li><a href="/vegetables/bulbs/leeks">Leeks</a></li>
					</ul>
				</li>
			</ul>
		</li>
	</ul>
</nav>

Without options

With no options specified, ActiveNav uses all its default settings.

<nav data-bc-activenav="true"...

<nav data-bc-activenav="true" class="activenav">
	<ul class="level">
		<li class="active"><a href="/animals">Animals</a>
			<ul>
				<li class="active"><a href="/animals/mammals">Mammals</a>
					<ul>
						<li><a href="/animals/mammals/land-mammals">Land Mammals</a></li>
						<li><a href="/animals/mammals/marine-mammals">Marine Mammals</a></li>
					</ul>
				</li>
				<li><a href="/animals/reptiles">Reptiles</a>
					<ul>
						<li><a href="/animals/reptiles/crocodiles">Crocodiles</a></li>
					</ul>
				</li>
			</ul>
		</li>
		<li><a href="/vegetables">Vegetables</a>
			<ul>
				<li><a href="/vegetables/roots">Roots</a>
					<ul>
						<li><a href="/vegetables/roots/carrots">Carrots</a></li>
						<li><a href="/vegetables/roots/parsnips">Parsnips</a></li>
					</ul>
				</li>
				<li><a href="/vegetables/bulbs">Bulbs</a>
					<ul>
						<li><a href="/vegetables/bulbs/garlic">Garlic</a></li>
						<li><a href="/vegetables/bulbs/leeks">Leeks</a></li>
					</ul>
				</li>
			</ul>
		</li>
	</ul>
</nav>

Specifying a level

ActiveNav's level option can drastically reduce the number of dynamic menus you need to create for a site. For example, say your primary navigation has three first-level items on it: Animals, Vegetables, Minerals. If your secondary nav is set to level:2, and you navigate to one of the animal pages, the secondary navigation will only have the links to the children of Animals. Others will be removed.

<nav data-bc-activenav="level:2"...

<nav data-bc-activenav="level:2" class="activenav">
	<ul class="level">
		<li class="active"><a href="/animals/mammals">Mammals</a>
			<ul>
				<li><a href="/animals/mammals/land-mammals">Land Mammals</a></li>
				<li><a href="/animals/mammals/marine-mammals">Marine Mammals</a></li>
			</ul>
		</li>
		<li><a href="/animals/reptiles">Reptiles</a>
			<ul>
				<li><a href="/animals/reptiles/crocodiles">Crocodiles</a></li>
			</ul>
		</li>
	</ul>
</nav>

Showing a title for the current level

It can be a nice UI feature to show a section title above the side navigation. In this case, that would be Animals. We can do this by setting levelTitle to levelTitle:true. That tells ActiveNav not to remove that link when it is removing the others. Additionally, setting unlinkTitle to unlinkTitle:true, will change the title from a link to a span.

<nav data-bc-activenav="level:2; levelTitle:true; unlinkTitle:true"...

<nav data-bc-activenav="level:2; levelTitle:true; unlinkTitle:true" class="activenav">
	<ul>
		<li class="leveltitle"><span>Animals</span>
			<ul class="level">
				<li class="active"><a href="/animals/mammals">Mammals</a>
					<ul>
						<li><a href="/animals/mammals/land-mammals">Land Mammals</a></li>
						<li><a href="/animals/mammals/marine-mammals">Marine Mammals</a></li>
					</ul>
				</li>
				<li><a href="/animals/reptiles">Reptiles</a>
					<ul>
						<li><a href="/animals/reptiles/crocodiles">Crocodiles</a></li>
					</ul>
				</li>
			</ul>
		</li>
	</ul>
</nav>

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.

Goto:

Usage

Options

Examples

Usage

Options

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.

Goto:

Usage

Options

Examples

Usage

Options

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.

Goto:

Usage

Options

Examples

Usage

Options

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.

	First Name
		
	
	Last Name
		
	

	Email Address
		
	
	Message
		
	
	Enter Word Verification in box below
		{module_captchav2}
	
	

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&amp;OID=15705642&amp;OTYPE=1&amp;EID=0&amp;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>

First Name Last Name Email Address Message Enter Word Verification in box below

(When the form submits, you'll get a "Page Not Found" error. That's on purpose.)

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&amp;OID=15705642&amp;OTYPE=1&amp;EID=0&amp;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>

First Name Last Name Email Address Message Enter Word Verification in box below

(When the form submits, you'll get a "You've deleted your web form" error. That's on purpose.)

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&amp;OID=15705642&amp;OTYPE=1&amp;EID=0&amp;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>

First Name Last Name Email Address Message

Home Address City State Zipcode/Postcode Country United States Cananda United Kingdom Australia Enter Word Verification in box below

(When the form submits, you'll get a "You've deleted your web form" error. That's on purpose.)

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.

Goto:

Usage

Options

Examples

Usage

Options

Examples

	Email
	Username


	

		

			

			
Shipping

			Address
			City
			State/Province
			Zip
			Country
				
					United States
					Cananda
					United Kingdom
					Australia
				
			
		

		

		

			 Same as Shipping?


			

				
Billing

				Address
				City
				State/Province
				Zip
				Country
					
						United States
						Cananda
						United Kingdom
						Australia
					
				
			

		

	

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.

Goto:

Usage

Options

Examples

Usage

Options

Examples

	

		
Home

		
Products

		
Contact Us

	

	
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.

Goto:

Usage

Options

Examples

Usage

Options

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>