Developer Documentation

How to build your own blocks.

Blockade is, at its core, a plugin for TinyMCE v4. As such, all add-ons are a php wrapper around their own TinyMCE plugins that have access to a set of public functions and handlers provided by the Blockade core. Becoming acquainted with with the TinyMCE v4 API and the Blockade source code (primarily the bundled add-ons that ship with Blockade core) is the best way to get started developing for Blockade.

In addition, we maintain a well-commented starter add-on that can be used to walk you through creation of your own add-on.

note: We discourage the use of jQuery in TinyMCE plugins. The interactions between the TinyMCE API and the jQuery library are not well known, and the use of jQuery reduces the overall portability of the Blockade ecosystem. There are several helper functions included in Blockade to help transition to vanilla JS.

Filters

Used to modify the behavior of Blockade’s PHP components

wp-blockade-override-post-types
modify which post types attach Blockade to the main editor (use to add blockade to custom post types)
wp-blockade-override-editors
modify which editors have Blockade attached (use to add blockade to custom metafields)
wp-blockade-tinymce-plugins
modify which tinymce plugins are loaded by Blockade (used in add-ons to register javascript)
wp-blockade-top-level-buttons
modify the buttons Blockade adds to the editor toolbar
wp-blockade-data-attributes
modify the set of attributes Blockade strips from the content
wp-blockade-disallowed-post-types
modify the set of post types blockade actively blocks
wp-blockade-register-addon-dir
register additional folders to search for add-ons (use to put add-ons in plugin directories)
wp-blockade-register-addon-dir
register additional folders to search for add-ons (use to put add-ons in plugin directories)
wp-blockade-available-addons
use to add or remove individual add-ons
wp-blockade-parse-path
use to parse new path variables in folders registered with wp-blockade-register-addon-dir

JavaScript Functions

Helpers for interacting with the Blockade Core.  Before using these functions in an add-on, you need to localize Blockade Core with
var blockade = editor.plugins.blockade;

blockade.addToMenu( item, submenu )
add an item to the main blockade menu. submenu is an optional argument that contains the title of the submenu to place the menu item in. item is an object, containing two attributes: name and either onclick or menu. onclick is a callback function. menu is an array of sub-items. several other attributes can be included in a menuitem object. see the TinyMCE API for more details.
blockade.options_make_accordion_html( title, content )
shortcut to generate html for an accordion within an options panel. title contains the text of the accordion’s header. content contains the html for the accordion’s content.
blockade.options_make_image_uploader_html( name, slug, datastr, del )
shortcut to generate html for an image uploader within an options panel. name contains the label for the uploader, slug contains the attribute name where the data will be stored, datastr contains any existing value returned by a previous uploader instance. del is an optional argument. if true, the image will be able to be removed, otherwise, it will only be able to be replaced with another image.
blockade.options_make_color_picker_html( name, slug, value )
shortcut to generate html for a colorpicker within an options panel. name contains the label for the colorpicker, slug contains the attribute name where the data will be stored, value contains the current value of the colorpicker.
blockade.options_make_select_box_html( name, slug, options, value )
shortcut to generate html for a selectbox within an options panel. name contains the label for the colorpicker, slug contains the attribute name where the data will be stored, options is an object containing value=>label pairs of options. value contains the current value of the selectbox.
blockade.isPlaceable( element )
returns true if element can contain other blocks, and is unlocked.
blockade.isEmptyish( element )
returns true if element is empty or contains only tinyMCE filler elements.
blockade.findInArray( needle, haystack )
returns the index of needle in haystack. returns -1 if not found.
blockade.removeActiveEditor()
deactivates any currently active content block.
blockade.createBlock( html )
wraps the included html in a generic block div.
blockade.convertToBlock( element )
add block attributes to the associated element.
blockade.placeBlock( element )
place the selected element at the closest placeable location to blockade.lastFocusedBlock.
blockade.hasClass( element, class )
returns true if element has the specified class
blockade.addClass( element, class )
adds the specified class to the element
blockade.removeClass( element, class )
removes the specified class from the element
blockade.toggleClass( element, class )
toggles the specified class on or off
blockade.getClassesByType( element )
returns the classes applied to an element, separated into two arrays: blockade and custom. the blockade array contains any class enumerated in the blockade.internalClasses array. custom contains all other classes.
blockade.getData( element, dataname )
shortcut to get the value of an element’s ‘data-dataname‘ attribute
blockade.setData( element, dataname, value )
shortcut to set the value of an element’s ‘data-dataname‘ attribute
blockade.getType( element )
get the type of a block. should return a key name in the blockade.contenttypes object.
blockade.setType( element, type )
set the type of a block. type should be a key name in the blockade.contenttypes object.
blockade.getRole( element )
get the role of an element. returns one of the roles enumerated in the blockade.roles object.
blockade.setRole( element, role )
set the role of an element. role should be a value in the blockade.roles object.
blockade.escapeHtml( html )
makes an html string safe for output in a textarea.
blockade.unescapeHtml( html )
converts an html string that was safed for output in a textarea back to valid html.
blockade.wrapInUndo( callback )
wraps the callback function in a TinyMCE undo transaction and execute it.

JavaScript Attributes

Attributes to consume or modify to interact with the Blockade Core.  Before using these attributes in an add-on, you need to localize Blockade Core with
var blockade = editor.plugins.blockade;

blockade.editor
a localized reference to the TinyMCE editor object.
blockade.document
a localized reference to the editor’s document object
blockade.body
a localized reference to the editor’s body element
blockade.idbase
the prefix used for all Blockade utility classes
blockade.classes
object containing all registered Blockade utility classes, keyed by their shorthand name.
blockade.internalClasses
array of all Blockade utility classes that may be applied to a Block.
blockade.datafields
object containning all custom data attributes added to block elements. keyed with shorthand for each attribute name.
blockade.roles
object containing roles that can be assigned to an element within a Block.
blockade.flags
object containing flags that can be assigned to a Block.
blockade.assets
object containing file assets for use by add-ons, such as the placeholder for missing images.
blockade.contenttypes
object that defines name and options screen behavior for each type of block. each named attribute corresponds to a different block type and contains the following attributes:
name
name of the block, for display in controlbar and options panel.
parse_block_data
function with arguments data and block. parses data needed for options screen from block and stores to data.type_specific then returns the data object.
render_html
function with argument data. returns either a string of html to render the default options tab or false to prevent rendering the default options tab. If you need to add multiple tabs or modify the default tabs, use render_options instead
render_options
function with argument data. returns an an object with named attributes containing html for each options tab to render (to remove default tabs, define them as false or null). This function overrides render_html
apply_form_results
function with arguments data, form_data, and block. data is the original parsed Block data. form_data is an object containing the data from the options panel. block is the block element that will be modified. modify block or return false to cancel.
blockade.lastFocusedBlock
element last in focus
blockade.menu
object containing all items in the main Blockade menu. used to remove or modify existing Blocks.