Cornerstone Plugin Integration

This article was last updated on the January 2, 2017.

Guidelines

Before you decide on integrating Cornerstone in your plugin, there are some things to consider.

Do’s and Don’ts

Please DO:

  • Create brand new Cornerstone elements.
  • Create Cornerstone elements to wrap your shortcodes, allowing them to be used in the page builder
  • Share with us your ideas, feedback, and thoughts, and even contributions if you like.

And some DO NOT’s:

  • Don’t change the markup of our elements or shortcodes. This is important for data portability.
  • Don’t alter the user interface in any way, including introducing new controls, or custom builder features.
  • Don’t extend existing elements with new controls, including sections, rows, and columns.

If you stick to our documented APIs, this won’t be a concern, but especially in WordPress, there are always workarounds, and we request that you avoid them.

We do understand this is more restrictive than what other builders allow, but we are committed to preserving the Cornerstone user experience – no matter what theme, or combination of plugins is used. We’re also committed to preserving the portability of content created with Cornerstone. If Cornerstone is lacking a certain control or feature you need, feel free to reach out and let us know. We may be able to work with you on making it part of the core plugin.

Functions and Hooks for Plugin Developers

Most Cornerstone plugin development will be focused around elements. There is much to cover, so the details of element creation will be in a separate article. Here we will focus on registering elements for use in the page builder, and settings up custom icons.

Element API

Everything covered here is also available in a working sample plugin that you can install, and copy code from as a starting point for your own elements.

The full element API is covered in a separate article.

Registering Custom elements

Before an element will appear in the page builder, it will need to be registered. As covered in the element API article, you will need a unique folder, and a definition.php file containing a PHP class. Inside the cornerstone_register_elements hook, you will then call the cornerstone_register_element function to complete the registration. Here’s what that function expects:

cornerstone_register_element( $class_name, $name, $path )

And a full code example

function my_extension_register_elements() {

    cornerstone_register_element( 'My_First_Element', 'my-first-element', MY_EXTENSION_PATH . 'includes/my-first-element' );
    cornerstone_register_element( 'My_Second_Element', 'my-second-element', MY_EXTENSION_PATH . 'includes/my-second-element' );

}

add_action( 'cornerstone_register_elements', 'my_extension_register_elements' );

Registering Element Icons

It’s possible to include your own icons to show in the library, but there are some considerations. These icons must be in an SVG format, and defined as symbols in an SVG file. Symbols allow a single file to hold any number of icons, and being a vector format, we can make better use of the icons within the page builder without requiring developers to include different states such as hover. It also helps enforce consistency, mentioned earlier as one of our goals.

First, you’ll need an SVG of the icon or logo you wish to use for the element. Next, convert it to use SVG <symbol> tags. For more information on this, see this article. Most often this is just replacing a wrapping <g></g> set, with <symbol></symbol> instead, including an ID attribute

An example would be:

<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"><svg xmlns="http://www.w3.org/2000/svg">
<symbol id="my-custom-element" viewBox="-290 382 30 30">
  <path d="M-262.1,403.9C-262.1,................."/>
</symbol>
<symbol id="another-custom-element" viewBox="-290 382 30 30">
  <path d="M-262.1,403.9C-262.1,................."/>
</symbol>
</svg>

Next, we want to make Cornerstone aware of this file. This involves using the cornerstone_icon_map filter to add a URL to the SVG you created containing your icon(s).

function my_extension_icon_map( $icon_map ) {
    $icon_map['my-extension'] = MY_EXTENSION_URL . '/assets/svg/icons.svg';
    return $icon_map;
}

add_filter( 'cornerstone_icon_map', 'my_extension_icon_map' );

At this point, my-extension can now be assigned as an icon_group, as covered in the UI section of the Custom Elements article.

Using an Integration Class

Integration classes are optional, but offer a convenient way to organize your code. With all the changes you may be including, it may help to organize them into a class. These class

Creating the class

Create a basic PHP class including a constructor. Optionally, you may include a static should_load function. For example:

<?php

class Cornerstone_Integration_My_Plugin {

  /**
   * This function is optional. Return true/false to determine if the integration should load.
   */
  public static function should_load() {
    return ( defined( 'MY_FEATURE') && MY_FEATURE );
  }

  /**
   * Loads during the plugins_loaded hook
   */
  public function __construct() {

  }

}

Register the Integration

Integrations need to be registered quite early to allow access to other primary hooks during execution. They are loaded by passing a name and class into the cornerstone_register_integration function. The best place to setup Cornerstone integration is is hooking into cornerstone_integrations somewhere during your plugin’s initialization.

<?php
function my_plugin_register_cornerstone_integration() {
  
  // Load the file containing the class previously created
  require( 'path/to/class-my-plugin-cornerstone-integration.php' );
  
  // Register our class with Cornerstone  
  cornerstone_register_integration( 'my-plugin', 'Cornerstone_Integration_My_Plugin' );

}
add_action( 'cornerstone_integrations', 'my_plugin_register_cornerstone_integration' );

Example

Here’s an example showing a class that registers some elements, and custom icons for your plugin.

<?php

class Cornerstone_Integration_My_Plugin {

  /**
   * Loads on the plugins_loaded hook
   */
  public function __construct() {

    // Register Custom Elements
    add_action( 'cornerstone_register_elements', array( $this, 'register_elements' ) ); 

    // Add Custom Icons
    add_filter( 'cornerstone_icon_map', array( $this, 'icon_map' ) );

  }

  public function register_elements() {

    cornerstone_register_element( 'My_First_Element', 'my-first-element', MY_EXTENSION_PATH . 'includes/my-first-element' );
    cornerstone_register_element( 'My_Second_Element', 'my-second-element', MY_EXTENSION_PATH . 'includes/my-second-element' );

  }

  public function icon_map( $icon_map ) {
    $icon_map['my-extension'] = MY_EXTENSION_URL . '/assets/svg/icons.svg';
    return $icon_map;
  }

}