ElmsPark Guides

Guides › Building your first PageMotor plugin

PageMotor guide

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 [my-hello-world] shortcode.

Plain PHP, no build step · One folder, one class · Checked against PageMotor 0.11.5

Five steps to a working plugin

  1. Folder and header Step 1. In your editor. One folder, one plugin.php.
  2. The class Step 2. In your editor. Already a valid plugin.
  3. A shortcode Step 3. In your editor. Your first capability.
  4. Activate it Step 4. In your site’s admin. Tick it, then Save Plugins.
  5. See it Step 5. On a page. Hello, world!
Connected to your site with an AI over MCP? It can write, install and activate the same plugin with no server access. See how →
Before you start

See the whole build in five minutes

▶ The whole build in 5 minutes 11 seconds, narrated, with captions: the header, the class, the CSS valet that silently loads nowhere, and what a crash costs you. Remade on 18 November 2026 to match the steps below.
Read the narration instead

The shape of it. Building your first PageMotor plugin. One folder, one PHP file. You declare a class, opt into the capabilities you need, activate it, and PageMotor does the rest. This takes you from an empty folder to a working shortcode.

Opt in, don’t hook in. The whole mental model first, because once you have it the rest is mechanical. A plugin is a folder under user-content/plugins, with a plugin.php inside it. That file declares a PHP class extending PM_Plugin. And you add capabilities by implementing valet methods: named methods that PageMotor calls at specific moments. Implement shortcodes, and you have shortcodes. Implement nothing at all, and you have a perfectly valid plugin that simply does nothing. You opt in, rather than hooking in.

The folder and the header. Step one, the folder and the header. Make your folder under user-content/plugins, and create plugin.php inside it. Name the folder in kebab case, and start it with a prefix unique to you or your organisation, so it cannot collide with anything else in the ecosystem. Then open that file and add the header comment. PageMotor reads that comment to identify the plugin, so it must sit at the very top of the file, before any PHP code at all.

Only the first 2 KB are read. Here is the first thing that catches people. PageMotor reads only the opening two kilobytes of plugin.php when it looks for the headers. Push a header below a long description or licence block, and PageMotor simply never sees it. Nothing errors, nothing warns you, the field is just quietly blank. So keep the header comment short, and keep it at the very top of the file.

The class, and the name that must match. Step two, the class. Directly below the header comment, declare a class that extends PM_Plugin, and give it a title. That is a complete, valid plugin. It does nothing yet, but PageMotor can load it and activate it. One thing to be careful about: the class name must match the Class field in the header exactly. PageMotor instantiates the class by reading that header, so a typo in either place means the plugin simply will not load.

construct, then init. The base class gives you two override slots for your own start-up code. Construct runs early, before your settings are loaded: use it for database setup, includes, anything that has to exist before the rest. And init runs once your valets are registered and your settings are loaded: use that for work which depends on them. There are also two you must leave alone. __construct() and _init() are framework-owned. Those two are not yours to touch.

Add a capability. Step three, adding an actual capability. To register a shortcode, implement the shortcodes valet. It returns an array mapping shortcode names to method names on your own class. Prefix the shortcode name, as you did the folder, because the first plugin to claim a name wins it. Then write the handler. It receives any attributes as an args array, escapes them with PageMotor's own text method, and returns its HTML. Note that word: returns. It does not echo. Get that the wrong way round and your output jumps to the wrong place on the page.

Shortcodes need css_sitewide(). Now the second thing that catches people, and it is worth knowing before it costs you an afternoon. If your shortcode needs its own CSS, register it with css_sitewide(), not plain css(). The plain one only loads when an instance of the plugin has been placed in the current page template, which is exactly right for Blocks and Containers. But a shortcode can appear on any page at all. So its styles have to be sitewide, or they will be missing precisely where you did not think to test.

Activate it, then use it. Steps four and five. Put the folder on the server, then in the admin go to Plugins. Yours appears in the list under the Name from your header. Tick the box beside it and click Save Plugins. That activates it: the class is loaded, and its valets run on every page load. Uploading the folder on its own only lists it. Or, if your AI is connected to your site over MCP, it can install the plugin and switch it on for you, with no server login at all. Then edit any page, drop the shortcode into the body, and save. Shortcodes run in page content, not in an uploaded HTML document, so if your output does not appear, check what you are editing before you go looking through your code.

A crash still costs you. And one last thing, which is the reason to keep early plugins simple. PageMotor includes your plugin file directly. If the file crashes while it loads, that request fails, and PageMotor switches the plugin off and tells you so in the admin. But a crash inside your shortcode handler is not caught: every page that uses it breaks until you fix it. Work with a safety copy, test each change as you make it, and if something breaks, fix the file before you do anything else.

Before you start

What you’ll need

  • A PageMotor site you can add plugins to: your own development site, or a staging site with admin access.
  • Basic PHP and a text editor. No Composer, no npm, no other tooling.
  • A way to put files on the server (upload, SFTP or a file manager), or an AI connected to your site over MCP.
  • About 20 minutes.

How PageMotor plugins work. A plugin is a folder inside user-content/plugins/ containing a plugin.php file. That file declares a PHP class which extends PM_Plugin, the framework’s base class. PageMotor reads the header comment at the top and lists the plugin in the admin. You add capabilities by implementing valet methods: named methods on your class that PageMotor calls at specific moments to register shortcodes, assets, AJAX handlers, settings, and more. Activate the plugin and those capabilities go live.

▶ Prefer to learn it interactively? Tap through the interactive lesson, one idea at a time, about two minutes, with quick questions as you go.

Use this guide with any AI assistant

Download it as a prompt file, paste it into Claude, ChatGPT, Gemini or any LLM, and it will walk you through building the plugin step by step.

Download as LLM prompt
The build Stage 1 of 2

Stage 1: Write it

  • Where you work In your text editor
  • What you do Steps 1 to 3
  • You finish with A complete plugin.php with one shortcode

Step 1 Make the folder and the header

Where: In your editor, inside user-content/plugins/

All third-party plugins live under user-content/plugins/ in your PageMotor install. Create a folder there for your plugin. The name should be lowercase kebab-case and should start with a prefix that is unique to you or your organisation, so it cannot collide with any other plugin in the ecosystem. (The pm- prefix is for PageMotor’s own plugins.)

First, pick your prefix and use it everywhere. Start your folder name, your class name and your shortcode tags with something unique to you. ElmsPark’s plugins use ep- folders and EP_ classes; this guide uses my- and My_.

The class name matters most. PageMotor’s own plugins have plain names such as Favicon, Open_Graph and Text_Box. Give your class one of those names and PageMotor skips your plugin. The only warning is in the admin; an AI calling activate-plugin is even told it worked (details).

For this guide, the folder is my-hello-world:

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

Open plugin.php and add the header comment. PageMotor reads this comment to identify the plugin, so it must appear at the very top of the file, before any PHP code:

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

The fields that matter for a first plugin:

  • Name: Required. The display name shown in Manage Plugins.
  • Description: A short description, also shown in Manage Plugins. Optional for a plugin you upload yourself, but an AI installing over MCP must send it (see below).
  • Version: Required. Shown as the version badge, and used to cache-bust your plugin’s CSS and JS; bump it when you change things.
  • Requires: The oldest PageMotor version your plugin works with. Set it to match what your install is running.
  • Class: Required. The exact PHP class name PageMotor will instantiate. Start it with your prefix, and match the class declaration below, including capital letters.

Keep the header near the top. PageMotor reads only the first 2 KB (2,048 bytes) of plugin.php to find the headers. A header pushed below a long comment block is simply not seen: nothing errors, the field is just blank.

Step 2 The plugin class

Where: In your editor, in plugin.php

Directly below the header comment, declare your class. It must extend PM_Plugin, and the class name must match the Class: field in the header exactly. Give it a $title: PageMotor’s own docs say every plugin should declare one, because that is how it is named in the admin screens.

<?php
/*
Name: My Hello World
...
Class: My_Hello_World
*/
class My_Hello_World extends PM_Plugin {
    public $title = 'My Hello World';

}

That is a complete, valid plugin. It does nothing yet, but PageMotor can load and activate it.

Two lifecycle slots you can override. PM_Plugin gives you two protected methods for your own code. construct() runs early, before your settings are loaded: use it for database setup, includes, or anything that must exist first. init() runs after the plugin has registered its valets and loaded its settings: use it for work that depends on them. Do not override __construct() or _init(): those are framework-owned and must not be touched.

Step 3 Add a capability: a shortcode

Where: In your editor, in plugin.php

Capabilities are added by implementing valet methods. To register a shortcode, implement shortcodes(). It returns an array mapping shortcode names to method names on your class.

Here is the complete plugin with one [my-hello-world] shortcode. This is the whole file:

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

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

    // The handler receives an $args array of any attributes
    public function render_hello($args = []) {
        global $motor;
        $name = !empty($args['name']) ? $args['name'] : 'world';
        return '<span class="my-hello-world">Hello, '.
            $motor->text($name, 'no-html'). '!</span>';
    }
}

The shortcode handler receives any attributes as $args and must return its HTML, not echo it. So [my-hello-world name="Kenn"] returns <span class="my-hello-world">Hello, Kenn!</span>.

  • Why $motor->text()? It is PageMotor’s own escaping method. 'no-html' escapes whatever a visitor or editor typed into name, so it cannot inject markup. PageMotor’s docs ask for it in place of PHP’s own escaping functions.
  • Why the my- on the tag? Shortcode tags share one namespace with core and every other plugin, and the first to claim a tag wins. Prefix yours, as you did the folder, so nothing can shadow it.

Frontend CSS for shortcodes. If your shortcode needs its own CSS, register it with css_sitewide(), not css(). The css() method only loads when an instance of the plugin is placed in the current page template. Shortcodes can appear on any page, so they need css_sitewide() to load on every page. This is a common early mistake. How to register the file.

The build Stage 2 of 2

Stage 2: Switch it on

  • Where you work In your site’s admin, then on a page
  • What you do Steps 4 and 5
  • You finish with Hello, world! on a live page

Step 4 Activate it

Where: In your site’s admin, Manage Plugins

Skip check Using an AI over MCP? It can put the folder on the server and activate it in two calls, with no upload and no admin clicks. See Let your AI install it, then come back for Step 5.

Put the my-hello-world folder on the server in user-content/plugins/, or zip the folder and use Upload a New Plugin at the top of Manage Plugins. Then, in your PageMotor admin:

  1. Open Plugins (Manage Plugins). Your plugin is in the list, under the Name: from its header, with its version beside it.
  2. Tick the box next to it.
  3. Click the green Save Plugins button at the top right. The plugin is now active: its class is loaded and its valets run on every page load.

A fatal error in plugin.php still costs you a page load. PageMotor includes the plugin file directly. If it crashes while loading (a syntax error, say), that request fails, PageMotor switches the plugin off, and the admin shows “crashed while loading and was automatically disabled”. A crash later on, inside your shortcode handler for example, is not caught: every page that uses the shortcode breaks until the file is fixed. Keep early plugins simple and test each change.

Step 5 See it on a page

Where: In the content editor, then on the live page

Edit any page in the PageMotor content editor and add the shortcode to the page body:

[my-hello-world]

Save, visit the page, and you should see Hello, world! rendered in the page output.

Try it with an attribute:

[my-hello-world name="Kenn"]

That should give you Hello, Kenn! The shortcode is live and working.

Shortcodes run in page content, not in an HTML document. A Page (and other content the theme renders) runs through the shortcode pipeline. The HTML content type is different: it is a whole HTML document you upload, served exactly as written, so shortcodes in it are never processed. If you see the raw [my-hello-world] text, check which content type you are editing.

Going further

Let your AI write it, install it and switch it on

If your AI assistant is connected to your site over MCP (Claude, ChatGPT or any MCP client), it can do Steps 1 to 4 for you. PageMotor’s own PM_Plugins actions accept the plugin as text, so nobody needs a server login, SFTP or a VPS.

  1. install-plugin: The AI sends a folder name and the files as text (or a zip). PageMotor checks the code, writes it to user-content/plugins/ and replies with the class name. It does not switch it on.
  2. activate-plugin: The AI sends the class name, for example My_Hello_World. The plugin is live from the next page load.
  3. update-plugin: For every change after that. It swaps in the new files with a backup, and an active plugin stays active.

You can simply ask: “Build me a PageMotor plugin that adds a [my-hello-world] shortcode, install it on my site and activate it.” The AI finds these actions itself through list-actions; your site’s MCP server tells it to.

Two things to know. Your token needs at least producer access, because installing a plugin is installing code: PageMotor’s own description of install-plugin says its checks are not a sandbox, so only install plugins from sources you trust. And install-plugin refuses a plugin.php without Name, Description, Version and Class headers, which is why the example above carries a description.

Your own admin dashboard, as a small plugin

Since PageMotor 0.10, a plugin can become the admin dashboard. Mark it Admin-only with Type: Admin in its header, set public $dashboard = true, and give it an html() method. Whatever html() prints is what you see at /admin/dashboard. No theme work, no template editing.

<?php
/*
Name: My Dashboard
Author: Your Name
Description: My own admin dashboard.
Version: 1.0
Requires: 0.11.5
Type: Admin
Class: My_Dashboard
License: OpenAttribution
*/
class My_Dashboard extends PM_Plugin {
    public $title = 'My Dashboard';
    public $dashboard = true;

    public function html($depth = 0) {
        global $motor;
        $tab = str_repeat("\t", $depth);
        echo
            "$tab<div class=\"my-dashboard\">\n".
            "$tab\t<h2>Good to see you</h2>\n".
            "$tab\t<p>This page is my own plugin.</p>\n".
            "$tab\t<p><a href=\"". $motor->admin_url('plugins').
                "\">Manage plugins</a></p>\n".
            "$tab</div>\n";
    }
}
  • It is the whole page. On 0.11.5 your html() fills the dashboard by itself, so link to the admin screens you use from it, as the example links to Manage Plugins.
  • It is live. Deactivate the plugin and the standard dashboard comes back. If two active plugins both claim the dashboard, the first one wins.
  • html() echoes. Unlike a shortcode handler, an output method prints its HTML and takes a $depth parameter for indentation.

Both examples on this page were proved on 18 November 2026 on a fresh PageMotor 0.11.5 site: installed with install-plugin, switched on with activate-plugin, both over MCP with no server access. The shortcode rendered Hello, world! and Hello, Kenn! on a page, and /admin/dashboard showed the dashboard plugin’s own HTML. Both files also pass PageMotor’s own plugin validator.

Reference

The valet methods you can implement

Checked against lib/plugin.php and lib/docs/plugin-valet-methods.md in PageMotor 0.11.5. Each method is optional; return an empty array [] from any array-returning valet when you have nothing to declare. These are the ones a first plugin is most likely to use.

Add a capability

  • shortcodes(): Returns ['tag' => 'method_name']. Maps shortcode tags to handler methods on your class. Handlers receive $args and return HTML.
  • settings(): Declares the plugin’s settings fields, which gives it a Settings button in Manage Plugins. Saved values arrive in $this->settings.
  • ajax(): Returns a flat map, ['action-id' => ['method' => 'handler']], of AJAX actions handled by public methods on your class.
  • api(): Declares API actions, grouped by family: ['family' => ['action-id' => [...]]]. These are also what an AI sees and calls over MCP.
  • content_type(): Registers one new content type (one per plugin).
  • fonts() and google_fonts(): Register fonts with PageMotor’s font system, so they appear in the font selectors.
  • skills(): Registers MCP Skills: guided workflows offered to AI agents.
  • docs(): Registers your plugin’s own documentation files with PageMotor’s doc system, so the API and AI agents can read them.

Load CSS and JavaScript

  • css_sitewide(): An asset array of CSS loaded on every front-end page. Use it for shortcode styles (see Step 3).
  • css(): CSS loaded only when this plugin is placed in the current template. For Box and Container output, not shortcodes.
  • register_js(): Registers scripts by ID so they can be queued. Registering alone puts nothing on a page.
  • js_sitewide(): Script IDs to output before </body> on every page.
  • js(): Script IDs to output only when this plugin appears in the current template.
  • js_head(): An asset array of JS output in <head> on every page. Only for scripts that must load there.

Print HTML

  • html($depth = 0): For $type = 'box' plugins: echoes the Box’s HTML when it is rendered in a template. For a $dashboard plugin: echoes the admin dashboard. Must echo, not return.
  • container_open($depth = 0): For $type = 'container' plugins: echoes HTML before the contained boxes.
  • container_close($depth = 0): For $type = 'container' plugins: echoes HTML after the contained boxes.

Your own setup code

  • construct(): Protected override slot. Runs early, before settings are loaded. Use it for database tables, includes and constants.
  • init(): Protected override slot. Runs once the plugin’s valets are registered and its settings are loaded.
  • preload(): Runs before the template renders, only when the plugin is in the current template. Safe for redirects.

There are more: Open Graph and structured data, email transports, read keys, endpoints and the options family among them. The full list, with exact return shapes and examples, is in PageMotor’s own lib/docs/plugin-valet-methods.md; an AI connected over MCP can ask for it with PM_Docs list-valets. ElmsPark’s plugin documentation is at documentation.elmspark.com/plugins/.

Reference

Settings, AJAX and assets, briefly

The three things most plugins need after a shortcode.

Settings. Implement settings() to give your plugin a settings page in the PageMotor admin: a Settings button appears beside it in Manage Plugins. It returns an array of field definitions. PageMotor handles the form, saving and retrieval. Saved values are available inside your methods as $this->settings['field_name'], from init() onwards.

AJAX. Implement ajax() and return ['action-id' => ['method' => 'ajax_handler']]. Action IDs must not start with an underscore (that prefix is reserved for framework actions), and handlers must be public. PageMotor checks the CSRF token for signed-in users and the access tier (producer unless you set 'access') before your handler runs; your job is to do the work and echo json_encode([...]). Your JavaScript posts pm_ajax (your class name) and action.

Assets. Register JS and CSS with the valet for where it needs to load: sitewide (every page) or template-scoped (only where the plugin is placed). Shortcodes need sitewide. PageMotor defines two constants for you from your class name, the folder path and its URL, so a stylesheet is ['my-hello-world' => ['url' => MY_HELLO_WORLD_URL. '/css/hello.css']]. Your Version: is added to the URL, so bump it when the CSS changes.

Reference

The early pitfalls

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

  • A crash in plugin.php still breaks things. A fatal error while the plugin loads costs one failed request, then PageMotor switches the plugin off and says so in the admin. A fatal inside a method that runs later, such as your shortcode handler, breaks every page that calls it. 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 activated to run. Putting the folder on the server only lists it. Tick it in Manage Plugins and click Save Plugins, or have your AI call activate-plugin. Boxes and Containers also have to be placed in a template before they render on the front end.
  • The class name must match the Class: header exactly, and carry your prefix. PHP class names are case-sensitive, and PageMotor instantiates the class by reading the header. A typo in either place means the plugin will not load. A plain name like Favicon clashes with PageMotor’s own plugin, and yours is skipped.
  • Return [], not null or nothing. Valet methods that return arrays should return an empty array when there is nothing to declare. The base class defaults are all return []; so you only need to implement the valets you actually use.
  • Shortcodes only fire in page content. An uploaded HTML document is served verbatim and its shortcodes are never processed.
  • Escape with $motor->text() and prefix your tags. Anything a person typed goes through $motor->text() before it reaches the page. Shortcode tags are first come, first served across the whole site, so an unprefixed [hello] may already belong to someone else.
Help

Troubleshooting

The most common problems and what to do about them. Open these only if you hit them.

The plugin does not appear in Manage Plugins

Check that the folder is directly inside user-content/plugins/ and that plugin.php is inside it (not in a sub-folder, which is easy to do when unzipping). Make sure the header comment is at the top of the file and that it has Name:, Version: and Class: lines. If another plugin already uses the same class name, PageMotor skips yours and says so in the admin: rename the class.

It says “activated”, but nothing of mine runs

Your class name is probably already taken, usually by one of PageMotor’s own plugins (Favicon, Open_Graph, Text_Box and the like). The first registration wins, so PageMotor skips yours. On PageMotor 0.11.5 install-plugin accepts the folder and activate-plugin still replies with success. The one warning, “declares class … already registered”, shows in the admin and in PM_Status list-notifications. Rename the class (and its Class: header) with your prefix, as described in Step 1.

PageMotor says the plugin “crashed while loading and was automatically disabled”

There is a PHP fatal error in plugin.php, or in your construct() or init(). The rest of the site is already back. Open the file and look for the mistake: a missing semicolon, an unclosed bracket, or a call to a class or function that does not exist. Running php -l plugin.php finds syntax errors. Then re-activate the plugin; it stays off until you do.

Pages went blank or show an error after adding the shortcode

The crash is inside a method that runs while the page renders, usually the shortcode handler, and PageMotor does not switch the plugin off for that. Fix the method, or deactivate the plugin in Manage Plugins to bring the pages back. If you cannot reach the admin, rename the plugin folder on the server (so PageMotor cannot include it), then fix the file at your own pace.

The shortcode appears on the page as plain text, not rendered

Three possibilities. First, the plugin may not be active: check Manage Plugins. Second, you may be editing an HTML document (the HTML content type), which is served verbatim; shortcodes only run in Page content and other content the theme renders. Third, check the tag in the page matches the key in shortcodes() exactly, and that the method it names exists and is public.

The shortcode renders but its CSS is not loading

You are probably using css() instead of css_sitewide(). The css() method only fires when the plugin is placed in the current template as a Box or Container. Switch to css_sitewide() for any styles that need to load alongside a shortcode. Still old styles? Bump Version:: it is added to the stylesheet URL to break browser caches.

The version shows blank in Manage Plugins

PageMotor reads only the first 2 KB (2,048 bytes) of plugin.php to find the headers. Move the header comment to the very top of the file, before any long description or licence text, and check the line reads Version: 1.0 with a colon. Nothing else is needed: PageMotor defines your class-name constants itself.

My AI’s install-plugin call was refused

The reply says why. The common ones: missing_header (add the Name, Description, Version and Class headers), wrong_base_class (the class must extend PM_Plugin), folder_exists (that folder is already installed: use update-plugin to replace it) and invalid_folder (use a lowercase, dash-separated folder name). A refusal for permissions means the token is below producer access.

See also: ElmsPark plugin documentation (valet method reference, examples) · More ElmsPark guides

Help

Sources

Checked 18 November 2026 against PageMotor 0.11.5:

  • PageMotor core lib/plugin.php: the PM_Plugin base class, every valet method’s default, the $title, $type and $dashboard properties, and the shortcode registration loop.
  • PageMotor core lib/plugins.php and lib/tools/files.php: how plugins are found, the 2,048-byte header read, the automatic switch-off after a crash while loading, Manage Plugins, and the install-plugin, update-plugin and activate-plugin actions.
  • PageMotor core docs lib/docs/plugin-filesystem.md, plugin-properties.md and plugin-valet-methods.md: headers, naming, the dashboard property, shortcodes, AJAX and assets.
  • A fresh PageMotor 0.11.5 test site, 18 November 2026: both example plugins installed and activated over MCP and seen working, and both passed PageMotor’s plugin validator.

First published 25 June 2026 against PageMotor 0.9.4b; rewritten for 0.11.5 on 18 November 2026.