Custom JavaScript

Custom JavaScript requires basic to moderate HTML/JS skills. Custom JavaScript can be useful in combination with custom templates.

Location Joomla:
/components/com_configbox/data/customization/assets/javascript/custom.js

Location Wordpress:
/wp-content/plugins/configbox/app/data/configbox-customization/assets/javascript/custom.js 

Location Magento 2:
/app/code/Rovexo/ConfigboxCustomizations/view/base/web/javascript/custom.js

See this article about installing the Magento 2 customization module.

  • This file gets loaded on any page that ConfigBox adds content to

  • When you create a minified file (custom.min.js) ConfigBox will load this file instead

  • You need to create this file on your server

Use of AMD modules using require.js

CB uses require.js as AMD loader and you can take advantage of this in your custom JS. The rest of this article is about using the custom.js file as AMD module. You can also opt to place any JS code in this file and have it executed.

Structuring the custom.js file as AMD module

The module ID of the custom JS file is 'configbox/custom/custom'. Use this typical structure to make the custom.js an AMD module:

1 2 3 4 define(['cbj'], function($) { // return an object if you have a use for it in other modules. // In the example we require jQuery, you'll have it as $ in your module. See below for more info on jQuery and plugins. });

 

Using jQuery within your AMD module

For jQuery you require the module 'cbj', as in the example above. ConfigBox ships with the latest jQuery version and upgrades during minor releases.

Requiring other custom AMD modules

If you want to create multiple AMD modules in your customisation directory, you can do that by creating the files and use the right module ID. ConfigBox defines a require.js path in it's configuration, for the customisation directory it is 'configbox/custom'. To add, for example, a module called 'module1', add the file module1.js and require it using the module ID 'configbox/custom/module1'

Example:

This sample is your custom.js file. Assume you have a module file called module1.js in your customisation directory already.

1 2 3 define(['configbox/custom/module1'], function(module1) { });

Here, the same, requiring both jQuery and module1

1 2 3 define(['cbj', 'configbox/custom/module1'], function($, module1) { });

Here - going a step further - you require both modules and also require another module (module2) during runtime 

1 2 3 4 5 6 7 define(['cbj', 'configbox/custom/module1'], function($, module1) { cbrequire(['configbox/custom/module2'], function(module2) { .. }); });

What is cbrequire? cbrequire is require.js' require function using ConfigBox' configuration, with mappings and various settings made. Always use it instead of require()

Having AMD modules loaded in custom ConfigBox views

Instead of leveraging your custom.js file to load modules and to execute JS code anywhere, you can add instructions to custom views to load specific AMD modules and optionally execute functions. See KenedoViews and AMD JS Modules

Using jQuery in your custom modules

We use jQuery 3 and upgrade jQuery regularly. We made strict isolation of 'our' jQuery from any jQuery library loaded in your CMS. Our jQuery does not write itself to the global scope and defines itself anonymously. To get a reference to jQuery, use this code

1 2 3 cbrequire(['cbj'], function($) { // Do stuff with $ });

Using jQuery plugins

Bundled plugins and their module IDs

  • cbj.ui: jQuery UI lastest version

  • cbj.bootstrap: Bootstrap 3

  • cbj.chosen: Chosen

  • cbj.colorbox: Colorbox jQuery plugin

  • tinyMCE: TinyMCE 4 

When you look at other modules CB comes with you'll see a bunch more. Stick to this list though, this is what we guarantee to keep during a major release, the rest may change in any update without notice.

Bringing in other jQuery plugins

Since our jQuery is not in the global scope, a slight modification is necessary if you include jQuery plugins. On the upside, you do not have to worry about dependencies.

When you add a jQuery plugin to the customisation folder, wrap the plugin code with this:

1 2 3 define(['cbj'], function(jQuery) { // Plugin code });

Sounds concerning, but it works reliably. Modifying standard plugins isn't great, but the benefits are - plus the modification is straight-forward. See how it's done in other jQuery plugins in the app folder at /assets/kenedo/external/jquery.*

Get jQuery with your plugin like this:

1 2 3 cbrequire(['configbox/custom/yourPlugin'], function($) { // $ gives you CB's jQuery with yourPlugin added to the fn list });