ContentBuilder.js Plugin Development

With plugins, you can extend ContentBuilder.js features or create additional functions according to your needs. A plugin can add an additional button into the ContentBuilder.js toolbar. So before we go into the plugin development, it is important to understand first the ContentBuilder.js toolbar and its configuration.

Please see also the readme.txt to get a quick overview on using the ContentBuilder.js.

Configuring Toolbar Buttons

The default ContentBuilder.js buttons are shown below:

To configure the buttons (to show, hide or change position), use buttons and buttonsMore parameters:

var obj = $.contentbuilder({
    container: '.container',
    buttons: ["bold", "italic", "createLink", "align", "color", "formatPara", "font", "formatting", "list", "textsettings", "image", "tags", "removeFormat"],
    buttonsMore: ["icon", "html", "preferences"]
});
  • The buttons parameter defines the main toolbar:

  • The buttonsMore parameter defines the second toolbar that is displayed when you click the More button:

Buttons from Installed Plugins

ContentBuilder.js has a pre-installed plugin named Preview plugin that is used for checking or viewing content on various screen sizes. The plugin adds a Preview button on the second toolbar.

The builder loads plugins based on the configuration in config.js file. Here you can modify the list of plugins installed:

config.js

//PLUGINS
_cb.settings.plugins = ['preview', 'buttoneditor'];

In this configuration, a buttoneditor plugin is also installed. However, this plugin doesn’t add a button on the toolbar.

An Example

Let’s try configuring toolbar buttons as follow:

var obj = $.contentbuilder({
    container: '.container',
    buttons: ["bold", "italic", "createLink"]
});

The toolbar will look like this:

And the second toolbar will still consist its default buttons:

If you want to remove the More button, first, set the buttonsMore parameter to empty array:

var obj = $.contentbuilder({
    container: '.container',
    buttons: ["bold", "italic", "createLink"],
    buttonsMore: []
});

Now only the Preview button from the plugin is displayed.

Remove the plugin by setting the plugin list (in config.js) to empty:

config.js

//PLUGINS
_cb.settings.plugin = [];

The More button is now removed:

Adding Add Snippet Button

You can add an Add Snippet button on the toolbar for adding content blocks.

There are two options:

  • First is by adding addSnippet on the buttons parameter.

var obj = $.contentbuilder({
    container: '.container',
    buttons: ["addSnippet", "bold", "italic", "createLink"],
    buttonsMore: []
});

  • Or, you can use toolbarAddSnippetButton parameter and set it to true:

var obj = $.contentbuilder({
    container: '.container',
    buttons: ["bold", "italic", "createLink"],
    buttonsMore: [],
    toolbarAddSnippetButton: true
});

Complete Button List

Here is the complete list of buttons you can use for configuring the toolbar:

    • addSnippet
    • bold
    • italic
    • createLink
    • align
    • color
    • formatPara
    • font
    • formatting
    • list
    • textSettings
    • image
    • tags
    • removeFormat
    • icon
    • html
    • preferences

Plugin Development

Plugins are placed in the contentbuilder/plugins/[plugin’s name] folder. For example, we created a plugin named helloworld. The location would be:

contentbuilder/plugins/helloworld/

In this folder, the plugin’s script file should be named: plugin.js.
Here is our helloworld's plugin.js code:

plugin.js

/*
    Hello World Plugin
*/

(function () {

    var button_html = '<button id="my_helloworld_button" title="Hello World" style="text-transform:none">hello</button>';

    _cb.addButton('helloworld', button_html, '#my_helloworld_button', function () {

        alert('Hello World');

    });

})();

In this example, we called an addButton() function to register a button and specify its callback function. The addButton() function has 4 parameters (see line 9 above):

1. Plugin's name

2. Button's HTML

3. Button's id

4. Callback function. Triggered on button's click.

Then, open the contentbuilder/config.js file and add the helloworld plugin into the plugins list:

config.js

//PLUGINS
_cb.settings.plugins = ['preview', 'buttoneditor', 'helloworld'];

Reload the builder and you will see a new helloworld button added on the toolbar:

Adding Button with an SVG Icon

Now we will modify our helloworld plugin to use icon for its button. For this, we use an addHtml() function to embed an SVG icon definition.

var icon_html = '<svg width="0" height="0" style="position:absolute;display:none;">' +
                    '<defs>' +
                        '<symbol viewBox="0 0 512 512" id="ion-alert"><path d="M320 480H192v-96h128v96zm-16-160h-96L192 32h128l-16 288z"></path></symbol>' + 
                     '</defs>' +
                '</svg>';

_cb.addHtml(icon_html);

Then the SVG icon can be used in our button. Here is the complete code (see line 16).

/*
    Hello World Plugin
*/

(function () {

    var icon_html = '<svg width="0" height="0" style="position:absolute;display:none;">' +
                    '<defs>' +
                        '<symbol viewBox="0 0 512 512" id="ion-alert"><path d="M320 480H192v-96h128v96zm-16-160h-96L192 32h128l-16 288z"></path></symbol>' + 
                     '</defs>' +
                '</svg>';

    _cb.addHtml(icon_html);

    var button_html = '<button id="my_helloworld_button" title="Hello World">' +
                    '<svg class="is-icon-flex" style="fill:rgba(0, 0, 0, 0.7);width:14px;height:14px;"><use xlink:href="content-builder/plugin-development.aspx#ion-alert"></use></svg>' +
                '</button>';

    _cb.addButton('helloworld', button_html, '#my_helloworld_button', function () {

        alert('Hello World');

    });

})();

Reload the builder and you will see that the icon is displayed:

Example: Creating a Plugin to Show/Hide Grid Outline

In this example, we will use a method addCss() to apply our custom stylesheet. We will add the following style:

<style>
	.container.showgrid > div > div {outline: 1px solid rgba(132, 132, 132, 0.27); outline-offset: 1px;}
</style>

When content container has the class showgrid, all blocks/columns will show an outline. So our plugin just needs to add/remove the showgrid class to show or hide grid outline.

Here is the complete code:

/*
Show Grid Plugin
*/

(function () {

    var icon_html = '<svg width="0" height="0" style="position:absolute;display:none;">' +
                    '<defs>' +
                        '<symbol viewBox="0 0 512 512" id="ion-ios-grid-view-outline"><path d="M448 192v-16H336V64h-16v112H192V64h-16v112H64v16h112v128H64v16h112v112h16V336h128v112h16V336h112v-16H336V192h112zM320 320H192V192h128v128z"></path></symbol>' +
                     '</defs>' +
                '</svg>';

    _cb.addHtml(icon_html);

    var css = '<style>' +
            '.container.showgrid > div > div {outline: 1px solid rgba(132, 132, 132, 0.27); outline-offset: 1px;}' +
        '</style>';

    _cb.addCss(css);

    var button_html = '<button id="btnShowGrid" title="Grid Outline">' +
                    '<svg class="is-icon-flex" style="fill:rgba(0, 0, 0, 0.7);width:14px;height:14px;"><use xlink:href="content-builder/plugin-development.aspx#ion-ios-grid-view-outline"></use></svg>' +
                '</button>';

    _cb.addButton('showgrid', button_html, '#btnShowGrid', function () {

        showGrid();

    });

    function showGrid() {
        if (jQuery('.container').hasClass('showgrid')) {
            jQuery('.container').removeClass('showgrid');
        } else {
            jQuery('.container').addClass('showgrid');
        }
    }

})();

As seen on the code, we add our stylesheet using the addCss() method (see line 19). Then, on button click, we call a function that adds or removes the showgrid class on the content container (se line 27 and 31-37).

Useful Methods for Creating Plugins

In addition to the addButton(), addHtml() and addCss() methods, here are useful methods you can use:

includeCss(filename)

Include a css file for plugin use.

includeJs(filename, callback)

Include a js file for plugin use. Callback function is called after the js file fully loaded.

pasteHtmlAtCaret(html, selectPastedContent)

Insert an HTML into content at text cursor (caret) position. The selectPastedContent value is true or false. If set true, the inserted HTML will be automatically selected.

showModal(modalElement, overlayStay)

To display a custom modal.

Before using the showModal() method, you need to prepare and embed a modal HTML. The modal HTML format should be:

<div class="is-modal mymodal">
	<div style="max-width:300px;height:200px;">
		<div class="is-modal-bar is-draggable">
			<div class="is-modal-close">✕</div>
		</div>
		…modal content here.. 
	</div>
</div>

Please use the addHtml() to embed the modal HTML. Then to show the modal, call the showModal() method:

var $modal = $('.is-modal.mymodal');
_cb.showModal($modal);

The showModal() method has 2 parameters:

  • modalElement: the modal element (use jQuery selector to get the element)
  • overlayStay: true or false. If set true, clicking outside the dialog will not close the dialog.
hideModal(modalElement)

To hide modal dialog.

A simple example of using showModal() and hideModal() methods can be seen on the plugin named Word Count that is included in the ContentBuilder.js package. The plugin is located in:

contentbuilder\plugins\wordcount\plugin.js

To enable the plugin, edit config.js and add wordcount into the plugin list:

config.js

//PLUGINS
_cb.settings.plugins = ['preview', 'buttoneditor', 'wordcount'];
out(text)

To write text with multi-language support. For example, you write a text ‘Word Count’:

_cb.out(‘Word Count’);

With this, in contentbuilder/lang/[language code].js you can add

_txt[‘Word Count’] = '… translation here...';

For more info on multi-language support, please see readme.txt in the package.


Note
Plugins can be useful for improving ContentBuilder.js with custom editing features. If you have the ContentBuilder.js source code (SUPER license), you may find useful codes related with content editing that you can copy, modify and use for your plugin development.