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.
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.
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.
Update the Snippet
Update the src location of the script element to match the location where you uploaded the file.
Key Usage Concepts
- 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:
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.
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 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.
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.
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 firstname.lastname@example.org.
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.
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 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.
|Placement||On any empty element. Crumbs will be added inside.|
|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.|
With no options specified, Crumbs uses all its default settings.
Changing the separator
Here, we change the separator from / to ».
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.
|Placement||On any empty element. Date will add its contents inside the element.|
|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.|
|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.|
Without any options specified, and placed on an empty html element, Date outputs the current year in four digit format.
You can apply custom formatting to the date by using the format option.
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.
The subtract option is the opposite of add.
|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|
|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.|
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.
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:
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).
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.
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!
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.
|Placement||On any input, select, or textarea element.|
|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.|
|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.|
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.
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.
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.
|Placement||On any element. Most practical on the body element. UnSecure affects all the child elements of the element it is placed on.|
|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.|
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.
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.
|Placement||On a target element.|
|Required Options||At least one of the following: onClass, offClass, onCallback, or offCallback.|
|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'.|
Below are the styles and custom scripts that Trigger will use in the following examples.
Minimal options, speciy just onClass, the trigger and target will be element itself, the class will be applied on click(default event).
Different Trigger with toggle(on/off)
Different trigger specified with onClass, offClass and toggle
Self Trigger with toggle classes and callbacks
Callbacks will be executed at on and off events
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.