Building your first PageMotor plugin

A PageMotor plugin is one folder with one PHP file inside. You declare a class, opt into the capabilities you need, activate it, and PageMotor does the rest. This guide takes you from an empty folder to a working [hello-world] shortcode.

$ mkdir user-content/plugins/my-hello-world
$ touch user-content/plugins/my-hello-world/plugin.php

<?php
/*
Name: My Hello World
Author: Your Name
Description: A minimal first plugin with one shortcode.
Version: 1.0
Requires: 0.9
Class: My_Hello_World
License: OpenAttribution
*/

<?php
/*
Name: My Hello World
...
Class: My_Hello_World
*/
class My_Hello_World extends PM_Plugin {

}

<?php
/*
Name: My Hello World
Author: Your Name
Description: A minimal first plugin with one shortcode.
Version: 1.0
Requires: 0.9
Class: My_Hello_World
License: OpenAttribution
*/
class My_Hello_World extends PM_Plugin {

    // Register shortcodes: 'shortcode-name' => 'method_name'
    public function shortcodes() {
        return [
            'hello-world' => 'render_hello'
        ];
    }

    // The handler receives an $args array of any attributes
    public function render_hello($args = []) {
        $name = !empty($args['name']) ? htmlspecialchars($args['name']) : 'world';
        return '<p>Hello, ' . $name . '!</p>';
    }

}

[hello-world]

[hello-world name="Kenn"]

The valet methods you can implement

Verified against lib/plugin.php in PageMotor 0.9.4b. Each method is optional; return an empty array [] from any array-returning valet when you have nothing to declare.

The full list of valets, with their exact return shapes and examples, is in the PageMotor plugin valet methods documentation at documentation.elmspark.com/plugins/.

Settings, AJAX and assets, briefly

The three things most plugins need after a shortcode.

Settings

Implement settings() to give your plugin a settings panel in the PageMotor admin. It returns an array of field definitions. PageMotor handles the form rendering, saving, and retrieval. Saved values are available inside your methods as $this->settings['field_name'].

AJAX

Implement ajax() to add AJAX actions. Return a map of action IDs to handler method names. Action IDs must not start with an underscore (that prefix is reserved for framework actions). Inside a handler, PageMotor has already verified the CSRF token; your job is to do the work and echo json_encode([...]) the response.

Assets

Register JS and CSS with the appropriate valet for where you need it to load. The key distinction is sitewide (loads on every page) versus template-scoped (loads only when the plugin appears in the current template). Shortcodes need sitewide loading. Blocks and Containers can use the template-scoped variants to keep the page light.

The early pitfalls

The things that catch most people in their first few plugins.

• A syntax error in plugin.php takes the whole site down. PageMotor includes the file directly. A PHP parse error will break every page until the file is corrected or the plugin is removed. Work with a safety copy and test each change.
• CSS for shortcodes needs css_sitewide(), not css(). The css() method only fires when the plugin is placed in the current page template. Shortcodes can appear anywhere, so their styles must use css_sitewide() to load on every page.
• A plugin must be installed and activated to run. Just uploading the folder is not enough. Go to the Plugins section in admin, install it, then activate it. Some capabilities (Blocks, Containers) also require the plugin to be placed in a template instance before they render on the front end.
• The class name must match the Class: header exactly. PageMotor instantiates the class by reading the header. A typo in either place means the plugin will not load.
• Valet methods that return arrays should return [], not null or nothing, when there is nothing to declare. A null return floods the error log. The base class defaults are all return []; so you only need to implement the valets you actually use.
• Shortcodes only fire on pages with type=page. If the page is set to type=html, the content is served verbatim and shortcodes are not processed.

Troubleshooting

The most common problems and what to do about them.