Documentation › Block API

Block API

Headway’s Block API allows developers to offer their own block types to other Headway members in Headway Extend. Using the API, you define what kind of content the block contains, what options are available in the options panel for the block, and more. Any block you develop becomes a WordPress plugin, so it’s installed and activated like any other plugin. This article gives code examples for a fictional block we’ll call “Quote of the Day,” or “QOTD” for short.

Note: Examples here are very basic and don’t illustrate a fully functioning block. For more extensive code snippet examples, see Block API Examples.

Files to Include

Your block plugin consists of at least a main .php file with a name derived from your block’s name (for example, qotd.php). This file contains the header information WordPress needs to recognize, install, and run your plugin. See “Standard Plugin Information” on this WordPress Codex page for the code that’s needed in this file. This file will also contain some PHP. Though this file can contain the rest of the PHP code needed to run your block, it’s recommended that you create at least two more .php files:
block.php and block-options.php. Everything runs smoother when certain functions are in separate files. These instructions show what to do with three .php files rather than just one. You should have two small image files, icon.png and icon-white.png, to represent your block in the Visual Editor. Your plugin can include other files needed to make your block work, such as .css and images. When your files are ready, put them all in a .zip file.

Functions and Classes

Include these functions in the block’s PHP code. Remember, anywhere you see “qotd,” that’s just the example.

Define the Block’s Version (for Headway Extend)

If you’ll be providing your block to other Headway members via Extend, add this line to the main .php file after the header information.

define('QOTD_BLOCK_VERSION', '1.0');

Remember to update the version value here whenever you’re releasing a new version.

Register Your Block with WordPress

Use the following line of code after the main file’s header information to tell the plugin to run after Headway is running so that all of Headway’s classes and functions are loaded.

add_action('after_setup_theme', 'qotd_register');

… where qotd_register is your function for telling Headway to include the block. This function comes next.

Register Your Block with Headway

Add this function to tell Headway to include your block in the Visual Editor. The function makes sure Headway is activated first—otherwise, you’ll get errors.

function qotd_register() { 		
if ( !class_exists('Headway') ) 		
return; 		

require_once 'block.php'; 		
require_once 'block-options.php'; 		
return headway_register_block('HeadwayQotdBlock', plugins_url(false, __FILE__)); 	} 

Details:

  • The require_once lines are needed only if you have part of your code in additional .php files. These files are named here.
  • ‘HeadwayQotdBlock’ is the name of the class found in block.php.
  • plugins_url gives the path to the folder that contains the icons for the block—this can usually be left as is.

Enable Auto-updates in Headway Extend

If you’re offering your block to Headway members via Headway Extend, add this function at the end of your main .php file. It drives the plugin update notices in WordPress when someone using your block needs to upgrade to the latest version of your plugin.

add_action('init', 'qotd_extend_updater'); 	
function qotd_extend_updater() { 		
if ( !class_exists('HeadwayUpdaterAPI') )     		
return;       	

$updater = new HeadwayUpdaterAPI(array(
'slug' => 'qotd-block','path' => plugin_basename(__FILE__), 			
'name' => 'Quote of the Day Block', 
'type' => 'block', 
'current_version' => QOTD_BLOCK_VERSION 		)); 	}

When the Headway team adds your block to Headway Extend, they use your slug to add your block to HeadwayUpdaterAPI.

Add Your Block’s Behaviors

In block.php (or your equivalent), add the main class that defines what your block will do when the website is viewed:

class HeadwayQotdBlock extends HeadwayBlockAPI { 	
public $id = 'qotd-block'; 		
public $name = 'Quote of the Day'; 		
public $options_class = 'HeadwayQotdBlockOptions'; 		
public $description = 'Displays a famous quote each day, adding some fun quotational randomness to your website.';
}

Details:

Variable Possible Values Notes
$id Unique string
$name String Displayed in the Visual Editor as the block type.
$options_class String (class name) Uses the class name in block-options.php (or your equivalent).
$description String Value is the tooltip text that appears when you hover over the block name when selecting a block type. Limit the description to 140 characters.

The following methods for this class are optional except for the final one, “Add the Block’s Content,” which determines what your block displays in a browser. If you won’t be using any of these methods, don’t include them because Headway will try executing them even if the method is empty.

Enqueue Styles or Scripts

Within this class, use the enqueue_action method to enqueue styles or scripts that apply to your block. This method will be executed for each instance of your block on a page when the browser loads the page. This method uses the WordPress “wp” hook.

function enqueue_action($block_id) { 		
$block = HeadwayBlocksData::get_block($block_id); 		
/* YOUR CODE HERE */ 		
return; 	
}

Register Sidebars and Menus

This method registers your block as a sidebar, menu, or similar item so it can then be controlled through the WordPress admin panel. It’s executed for each instance of this block when a page is loaded.

function init_action($block_id) { 		
/* YOUR CODE HERE */ 		
return; 	
}

Insert JavaScript

Use this method to insert JavaScript into the page, such as initializing instances of jQuery Cycle or jQuery Tabs.

function dynamic_js($block_id) { 		
/* YOUR CODE HERE */ 		
return; 	
}

Insert CSS

CSS you add using this function will be inserted into CSS files rather than as inline CSS in style elements or attributes.

function dynamic_css($block_id) { 		
/* YOUR CODE HERE */ 		
return; 	
}

Register Elements for Design Mode

Use this function to register each element you want to be available for styling in Visual Editor Design Mode. (Styling options for blocks themselves are predefined.) Repeat the $this->register_block_element object for each element you want to provide styling options for.

function setup_elements() {	 		
$this->register_block_element(array(
'id' => 'example-id',
'name' => 'Example Element', 	
'selector' => '.example-element-selector',
'properties' => array('property1', 'property2', 'property3'),
 'states' => array( 
'Selected' => '.example-element-selector.selected',
'Hover' => '.example-element-selector:hover', 
'Clicked' => '.example-element:active') )); }

Details:

Parameter Index Type or Possible Values Notes
id Unique string Required for each element you register. Selectors can be changed later, but the ID will always be the same.
name Unique string Displays as a child of your block in the options panel when your block is selected. For example, when “Header” is selected in the options panel, the children “Site Title” and “Site Tagline” appear.
selector Unique string beginning with a period The selector tells Headway what class to use in the HTML. In your site’s CSS, this selector will be prefixed with .block-type- type, where type is a slug for the block type (see Headway CSS Map).
properties “fonts”
“borders”
“padding”
“rounded-corners”
“box-shadow”
“text-shadow”
Headway always includes the “Nudging” and “Margin” property groups, so you don’t need to add them here.
states Array (see next items) Sets selectors for link states. States are optional. If you don’t need to include states, remove the entire ‘states’ index and array from this function.
Selected The ‘selector’ string plus the .selected class Headway adds the selector to the CSS and the corresponding class to the HTML when the block is used. This class is used for navigation menu items corresponding to the current page.
Hover The ‘selector’ string plus the :hover pseudo-class Headway adds the selector to the CSS and the corresponding class to the HTML when the block is used.
Clicked The ‘selector’ string plus the :active pseudo-class Headway adds the selector to the CSS and the corresponding class to the HTML when the block is used.

Add the Block’s Content (Required)

This function determines your block’s core functionality—what is displayed in the block itself when the browser loads the page.

function content($block) { 		
/* YOUR CODE HERE */ 	
}

Set Your Block’s Options

In block-options.php (or your equivalent), add this class to tell Headway what options appear for your block in the Visual Editor options panel. For each subtab you want to appear in the options panel, you need one index and value pair under $tabs and corresponding arrays under $inputs. Notice that for $inputs, the arrays go two levels deep: one level that identifies the types of input for the subtab, and another level that sets the values for each type of input. This code shows an example of a single subtab with a single text input field.

class HeadwayExampleBlockOptions extends HeadwayBlockOptionsAPI { 		
public $tabs = array( 			
'my-first-tab' => 'Example'); 		
public $inputs = array( 			
'my-first-tab' => array( 				
'text-input' => array( 					
'type' => 'text', 					
'name' => 'my-text-input', 					
'label' => 'Text', 					
'default' => 'Type your text here.', 					
'tooltip' => 'Put anything relevant about the input in this tooltip.', 					
'callback' => "
/* YOUR JAVASCRIPT HERE */ 					
") ) ); 	
}

Details:

Index Type or Possible Values Notes
type “checkbox” (toggle on and off) “select” (dropdown) “colorpicker” (color picker window, including swatches) “image” (image uploader and selector) “integer” (number) “multi-select” (text area for selecting one or more items) “slider” (range of integers with slider control) “text” (single-line text field) “textarea” (multiple-line text box) “wysiwyg” (text area with formatting controls)
name Unique string This is the setting you retrieve from the database.
label String This is the text that is displayed with this control in the options panel.
default String (for the text and textarea types) Integer (for the integer and slider types) Array (for the multi-select type) “true” (for the checkbox type) “false” (for the checkbox type) Acceptable defaults are dependent on the input type, and not all input types can have defaults.
options Array Applicable only when the type is “select” or “multi-select.” The array contains the index and value pairs for the options you want to appear. For a “none” option (null), use an empty index with corresponding display text indicating no selection.
unit “px”
“%”
Used as a suffix on the input. Applicable only when the type is “integer” or “slider.”
slider-min Integer Applicable only when the type is “slider.”
slider-max Integer Applicable only when the type is “slider.”
slider-interval Integer The amount by which moving the slider one position will increment or decrement its value. Applicable only when the type is “slider.”
tooltip String Optional. If you add a tooltip, a help icon is displayed next to the control. Users see the tooltip if they hover over the icon.
callback JavaScript arguments Optional. Use to run JavaScript when the input changes. The variables available are “block” and “value.”

This article was last updated for Headway version 3.8.3

Copyright © 2016 Vesped Inc. All Rights Reserved. Proudly Powered by Headway and WordPress