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>
An example of using a data attribute to call a Dev-in-a-Box trick.

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>
This snippet goes just before the closing body tag on your page.

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>
data-bc-[trick name in lowercase letters]

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>
data-bc-[trick name in lowercase letters]="true"

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>
data-bc-[trick in lowercase letters]=”option1: value; option2: value;”

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.

Usage

Topic Usage
Data Attribute data-bc-activenav
Placement On any element surrounding an unordered list <div><ul>...</ul></div>
Required Options None

Options

Option Default Value Notes
navClassactivenavThe name of the class applied to your outermost navigation element. This helps you specify CSS rules that only target navigation that uses ActiveNav.
activeClassactiveThe name of the class applied to each <li> in the nav tree that falls between:

  1. an “active” link whose href matches the current url,

  2. and an element with the class determined by the levelClass option.

level1Indicates the depth at which a class name, determined by the levelClass option, is added to the navigation. Default is 1 (first <ul>).
levelClasslevelThe name of the class applied at the highest active level of the navigation.
lastLevel0Indicates the depth at which a class name, determined by the lastLevelClass option, is added to the navigation. Default is 0 (off).
lastLevelClasslastlevelThe name of the class applied to at the level indicated by lastlevel.
levelTitlefalseDisplays the parent link of your selected level, acting like a title for your navigation. Only works with level 2 or greater.
levelTitleClassleveltitleThe name of the class applied to levelTitle.
unlinkTitlefalseIf set to true, changes the levelTitle from an <a> to a <span> element.
removeHiddentrueRemoves the parent elements of level and the children of noChild from the DOM. Default is true. This is good for SEO (removes hidden content).
activeHashfalseIf set to true, ActiveNav will update the navigation when a matching anchor reaches a specified distance (set by hashOffset) from the top of the window.
hashSupporttrueIf true, ActiveNav will compare hashes between URLs and links in the navigation.
hashOffset30The distance in pixels between the hash target and the top of the screen, before it triggers the menu change on scroll.
removeClassAids in battling FOUC (flash of unstyled content) by allowing a designer to hard-code classes on their navigation (to make it appear a certain way on load), which will be removed after ActiveNav is finished initializing.

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.

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.
showHomefalseDetermines whether or not the breadcrumbs will begin with Home/.
homeTitleHomeIf 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
formatYYYYSyntax 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
momentautoShould 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.
eventloadspecify 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'.
reftextspecify 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'.
targettextSpecify 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
requiredClassrequiredThe name of the class FormMagic looks for when determining the required fields.
errorGroupElementdivThe element type that surrounds a required input after it fails validation. This element is created and removed dynamically.
errorGroupClasserror-groupThe name of the class applied to the errorGroupElement.
errorMessageElementsmallThe element type that contains the error message after a required input fails validation. This element is created and removed dynamically.
errorClasserrorThe name of the class applied to the errorMessageElement and the required input after failed validation.
messageBoxIDbcmodulesThe ID of the element used to receive the message after a successful Ajax submission. This works in conjuction with messageMode.
messageModeprependappend, 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.
afterAjaxremovehide, show Determines what to do with the form after receiving an Ajax response message.
useAjaxfalseDetermine if the form should be submitted through Ajax.
validateModealertThe 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]"...
fieldTitleAttrlabelor specify a field attribute
systemMessageClasssystem-messageThe 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
systemErrorMessageClasssystem-error-messageThe 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
successClasssuccess
submitEventnullkeyup, 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.
noSubmitfalsePrevents submission of the form.
ajaxErrornullspecify a function to run after an Ajax submission 'error' response
ajaxSuccessnullspecify a function to run after an Ajax submission 'success' response
ajaxCompletenullspecify a function to run after an Ajax submission 'complete' response
multistepfalseTrue if this is a multistep form or validations are to be done in steps
containersmultistep container selectors, separated by comma
continueButtonContinue button selector for multi step form
backButtonback button selector for multi step form
buttonAfterSubmitenableDetermines what to do with the submit button after a form submission completes. Possible values are none, enable, hide, show, disable.
buttonOnSubmitdisableDetermines what to do with the submit button while a form submission is in progress. Options are none, disable, or hide.
restoreMessageBoxtrueIf an ajax submission result is empty, the original contents of messageBox will be restored. This is particularly helpful with live searches.
validationErrornullSpecify a function to run after validation returns errors on submit.
validationSuccessnullSpecify 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&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>

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>

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>

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
copyRequired. Specifies the field whose value will be copied.
bothWaysfalseDetermines whether the two fields’ values will match, regardless of which field’s value is altered.
checkboxThe 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.
clearOnUnchecktrueDetermines whether or not copied values will be cleared when the checkbox is unchecked. This option is dependent on the checkbox option being set.
attributeTypenameAllows you to specify the html attribute type SameAs references in its 'copy' option.
breakOnChangefalseBreaks the SameAs link between the source and destination field if the source field value is changed. Requires bothWays:false.
copyTypesimpleDetermines 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.
eventchangespecify the event that triggers the copy.
prefiixPrepends the copied value with a specified string of characters.
refvalueor text.
scopeformUses 'form' or css selectors as values. This allows for setting a larger or smaller scope for SameAs as it searches for a source field.
suffixPrepends the copied value with a specified string of characters.

Examples









Shipping








Same as Shipping?



Billing








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>
Shipping
Same as Shipping?
Billing

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
onSessionEndAllows 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.
sessionEndRedirectAllows you to specify a path that the user will be redirected to when the system automatically logs a user out of the front-end.
unsecureLinkstrueWhen 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
eventclickThe event that will trigger the trick's behavior. Any jQuery event can be used here.
triggerselfSpecify the element that will act as the trigger.
triggerValueDependent 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.
togglefalseWhen 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.
onClassThe class that will be added to the target element when the trigger is set to 'on'.
offClassDependent 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.
onCallbackSpecifies a function to execute after a trigger is set to 'on'.
offCallbackDependent 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>
Hey there!

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>