Documentation › Block API Examples

Block API Examples

Interested in a downloadable example? Check out our block example on GitHub.

Complete Structure of Files

These
examples show the full structure of the PHP needed to run a custom
block. Some “my block” and “my selector” fillers are used as basic
examples. More detailed examples follow this section.

Main .php File

<?php
		define('MY_BLOCK_VERSION', '1.0');
		add_action('after_setup_theme', 'my_block_register');
		function my_block_register {
			if ( !class_exists('Headway') )
				return;
			require_once 'block.php';
			require_once 'block-options.php';
			return headway_register_block('HeadwayMyBlock', plugins_url(false, __FILE__));
		}
		add_action('init', 'my_block_extend_updater');
		function my_block_extend_updater() {
			if ( !class_exists('HeadwayUpdaterAPI') )
				return;
			$updater = new HeadwayUpdaterAPI(array(
				'slug' => 'my-block',
				'path' => plugin_basename(__FILE__),
				'name' => 'My Block',
				'type' => 'block',
				'current_version' => MY_BLOCK_VERSION
			));
		}

block.php

Includes all optional methods (remove any methods you aren’t using):

<?php
		class HeadwayMyBlock extends HeadwayBlockAPI {
  			public $id = 'my-block';
  			public $name = 'My Block Name';
  			public $options_class = 'HeadwayMyBlockOptions';
  			public $description = 'My description.'
			function enqueue_action($block_id) {
				/* CODE FOR OPTIONAL METHOD */
				return;
			}
			function init_action($block_id) {
				/* CODE FOR OPTIONAL METHOD */
				return;
			}
			function dynamic_js($block_id) {
				/* CODE FOR OPTIONAL METHOD */
				return;
			}
			function dynamic_css($block_id) {				
				/* CODE FOR OPTIONAL METHOD */
				return;
			}
			function setup_elements() {
				$this->register_block_element(array(
					'id' => 'element1-id',
					'name' => 'Element 1 Name',
					'selector' => '.my-selector1',
					'properties' => 'array('property1', 'property2', 'property3'),
					'states' => array(
						'Selected' => '.my-selector1.selected',
						'Hover' => '.my-selector1:hover',
						'Clicked' => '.my-selector1:active'
					)
				));
			}
			function content($block) {
				/* CODE HERE */
			}
		}

block-options.php

<?php
	class HeadwayMyBlockOptions extends HeadwayBlockOptionsAPI {
		public $tabs = array(
			'my-only-tab' => 'Settings'
		);
		public $inputs = array(
			'my-only-tab' => array(
				'text-input' => array(
					'type' => 'image',
					'name' => 'logo',
					'label' => 'Logo',
					'tooltip' => 'Put anything relevant about the input in this tooltip.'
				)
			)
		);
	}

Enqueue Action Example (block.php)

This function intializes FlexSlider, a jQuery carousel. If there are no images or only one image, FlexSlider won’t be loaded.

function enqueue_action($block_id, $block) {
		$images = parent::get_setting($block, 'images', array());
		wp_enqueue_style('flexslider', headway_url() . '/library/blocks/slider/assets/flexslider.css');
		if ( count($images) <= 1 )
			return false;
		wp_enqueue_script('flexslider', headway_url() . '/library/blocks/slider/assets/jquery.flexslider-min.js', array('jquery'));
	}

Register Sidebar or Menu Example (block.php)

This function registers the widget area block with WordPress so that it can have widgets added to it in the admin panel.

function init_action($block_id, $block) {
		$widget_area_name = HeadwayBlocksData::get_block_name($block) . ' — ' . 'Layout: ' . HeadwayLayout::get_name($block['layout']);
		$widget_area = array(
			'name' => $widget_area_name,
			'id' => 'widget-area-' . $block['id'],
			'before_widget' => '<li id="%1$s">' . "n",
			'after_widget' => '</li><!-- .widget -->' . "n",
			'before_title' => '<span>',
			'after_title' => '</span>' . "n",
		);
		register_sidebar($widget_area);
	}

Insert JavaScript Example (block.php)

This function
follows up on the enqueue action example by running the jQuery script.
It uses the values passed in from the block’s settings to build the
parameters.

function dynamic_js($block_id, $block) {
		$images = parent::get_setting($block, 'images', array());
		if ( count($images) <= 1 )
			return false;
			return '
				jQuery(document).ready(function(){
					jQuery('#block-' . $block['id'] . ' .flexslider').flexslider({
						animation: "' . (parent::get_setting($block, 'animation', 'slide-horizontal') == 'fade' ? 'fade' : 'slide') . '",
						direction: "' . (parent::get_setting($block, 'animation', 'slide-horizontal') == 'slide-vertical' ? 'vertical' : 'horizontal') . '",
						slideshow: ' . (parent::get_setting($block, 'slideshow', true) ? 'true' : 'false') . ',
						slideshowSpeed: ' . (parent::get_setting($block, 'animation-timeout', 6) * 1000) . ',
						animationSpeed: ' . (parent::get_setting($block, 'animation-speed', 500)) . ',
						randomize: false,
						controlNav: ' . (parent::get_setting($block, 'show-pager-nav', true) ? 'true' : 'false') . ',
						directionNav: ' . (parent::get_setting($block, 'show-direction-nav', true) ? 'true' : 'false') . ',
						randomize: ' . (parent::get_setting($block, 'randomize-order', false) ? 'true' : 'false') . '
					});
				});' . "n";
	}

Insert CSS Example (block.php)

This function first
checks to see if the block is mirroring, and if so, uses those settings.
If not, the additional CSS is inserted.

function dynamic_css($block_id, $block, $original_block = null) {
		$selector = '#block-' . $block_id;
			if ( is_array($original_block) ) {
				$block_id = $original_block['id'];
				$block = $original_block;
				$selector .= '.block-original-' . $block_id;
			}
		$block_height = HeadwayBlocksData::get_block_height($block);
			return '
				' . $selector . ' .nav-horizontal ul.menu > li > a,
				' . $selector . ' .nav-search-active .nav-search {
					height: ' . $block_height . 'px;
					line-height: ' . $block_height . 'px;
				}';
	}

Register Elements Example (block.php)

This function tells the Visual Editor that when your block, which we’ll call “X
Block,” is selected in the options panel, three child elements are
available for styling: Title, Tab, and Content. Because this is the X
Block, and to make our IDs and selectors unique, we’ll preface some
values with “x.”

function setup_elements() {
		$this->register_block_element(array(
			'id' => 'xtitle',
			'name' => 'Title',
			'selector' => '.xtitle',
			'properties' => 'array('fonts', 'borders', 'padding', 'text-shadow')
		));
		$this->register_block_element(array(
			'id' => 'xtab',
			'name' => 'Tab',
			'selector' => '.xtab',
			'properties' => 'array('fonts', 'borders', 'padding', 'text-shadow', rounded-corners'),
			'states' => array(
				'Selected' => '.xtab.selected',
				'Hover' => '.xtab:hover',
				'Clicked' => '.xtab:active'
			)
		));
		$this->register_block_element(array(
			'id' => 'xcontent',
			'name' => 'Content',
			'selector' => '.xcontent',
			'properties' => 'array('fonts', 'padding', 'text-shadow')
		));
	}

Block Content Example (block.php)

This example shows text being pulled from the database and displayed in the block. The
third argument in this function (in this example, “null”) is what will be returned if the setting is not present in the database.

function content($block) {
		$sample_input_value = parent::get_setting($block, 'sample-input', null);
		if ( $sample_input_value == null ) {
			echo '<p>The sample input has nothing in it yet!</p>';
		} else {
			echo '<p>Here's what the sample input has for a value: ' . $sample_input_value . '</p>';
		}
	}

Block Options Example (block-options.php)

This example has two tabs with two inputs each, including a sample JavaScript callback on the first input.

class HeadwayExampleBlockOptions extends HeadwayBlockOptionsAPI {
		public $tabs = array(
			'my-tab-1' => 'My First Tab',
			'my-tab-2' => 'My Second Tab',
		);
		public $inputs = array(
			'my-tab-1' => array(
				'input-1' => array(
					'type' => 'text',
					'name' => 'Input 1',
					'default' => '',
					'tooltip' => 'Input 1 help.',
					'callback' => "
						if ( value.length > 0 ) {
							block.find('.block-content p').text('Here's what the example input has for a value:' + value);
						} else {
							block.find('.block-content p').text('The example input has nothing in it yet!');
						}
					"
				)
				'input-2' => array(
					'type' => 'checkbox',
					'name' => 'Input 2',
					'default' => true,
					'tooltip' => ''
				)
			)
			'my-tab-2' => array(
				'input-3' => array(
					'type' => 'select',
					'name' => 'Input 3',
					'options' => array(
						'' => 'None',
						'eyes' => 'Eyes',
						'nose' => 'Nose',
						'mouth' => 'Mouth'
					)
					'default' => '',
					'tooltip' => 'Input 3 help.'
				)
				'input-4' => array(
					'type' => 'slider',
					'name' => 'Input 4',
					'default' => 10,
					'unit' => %,
					'slider-min' => 0,
					'slider-max' => 100,
					'slider-interval' => 1,
					'tooltip' => 'Input 4 help.'
				)
			)
		);
	}

This article was last updated for Headway version 3.8.3

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