Creating a Custom Module

Snowball has a modular architecture for handling many different content types. In addition to 20+ native modules, Snowball supports custom modules.

The Files

Each module is a bundle of HTML, JavaScript, and JSON files:

• admin.json
• admin.html
• admin.js
• template.html
• template.js

"Admin" refers to the module's interface when authoring an article in the WordPress Admin Area. "Template" refers to the output generated by the module in the article.

Place the folder containing your bundle of files at /wordpress/wp-content/uploads/snowball/modules/.

Remember to keep the gulp task running while you're developing a custom module. This task minifies the JavaScript files and concatenates them to generate admins.js and templates.js.

admin.json

This file defines the metadata for the custom module.

• name: Name of the module.
• iconClasses: Font Awesome class for the module's icon in the toolbar.
• tags: Space-separated list of categories that the module will be filtered by in the toolbar (basic, media, social, data, meta). Custom modules will automatically have a "custom" category as well.

admin.html

This file is where you create the admin interface for your module.

• The root element should be a <form> element.
• The values of <input> and <textarea> elements are automatically saved to the database.
• Use the data-target attribute to define where the value of an <input> or <textarea> is printed in template.html.

admin.js

This file is where you include any JavaScript required for the module's admin interface. This can be useful for initializing a library, loading data, calculating a value, or triggering an event.

• Wrap your script in an IIFE:

(function ($) {
    /* Put Content Here */ 
})(jQuery);

• When binding events, bind to #snowball-main and use event delegation to target your custom block.

$('#snowball-main').on('click', '.snowball-block-custom', function()...

• For dynamically generated data, store the value in an <input type="hidden"> element to save its state and use it in the module's template.

template.html

This file is used to generated the module's output based on the values set in the admin interface.

• The root element should be a <section> element.
• The <section> element should have two classes: snowball-block and snowball-block-[name_of_your_module].
• To output the value of any <input> or <textarea> found in admin.html, wrap its data-target value in {{ and }}. For example, the value of a <input type="text" data-target="size"> can be outputted using {{size}}`.
• Any styles used for module's output should be added in a <style scoped> element.

template.js

This file is where you include any JavaScript required for the module's output. This can be useful for initializing a library, loading data, calculating a value, or triggering an event.