Discovery 002 — What Is a PageMotor Plugin?

A PageMotor plugin is the primary way to connect new behavior and capabilities to a PageMotor site. Some plugins produce template-based HTML; others work entirely outside the Template Editor. Both follow the same basic class-based architecture.

Question

What is a PageMotor plugin, and what basic structure must a developer understand before building one?

Why This Matters

Developers arriving from WordPress may assume a plugin is simply an optional feature package. PageMotor uses a broader model. Chris Pearson describes plugins as the main way to connect to a site to accomplish almost anything: adding functionality, changing behavior, integrating outside systems, or adding styles and scripts.

That distinction changes the first design question. Instead of asking only, “What feature should this plugin add?” the developer should also ask, “What new capability should PageMotor gain?”

Plain-English Definition

A PageMotor plugin is a folder containing a plugin.php file that identifies the plugin through a metadata header and declares a PHP class extending PM_Plugin. The class describes what the plugin is and provides the methods PageMotor calls when the plugin performs its work.

developerprefix-pluginname/
    plugin.php
        metadata header
        plugin class extends PM_Plugin
        properties describing the plugin
        methods providing its behavior

Architectural Principle

Plugins are not merely add-ons. They are the primary connection point for extending what PageMotor can do.

Chris Pearson contrasts the older plugin mentality—adding a specific website feature—with PageMotor’s newer modality: plugins are the main way to connect to the website to accomplish anything.

Two Basic Flavors

PageMotor plugins come in two broad forms:

1. Plugins with template-based HTML output. These can appear in the Block Editor and be placed into templates.
2. Plugins without template-based HTML output. These perform other work and do not appear in the Block Editor unless they declare an HTML-output type.

Other than this distinction, Chris states that plugins are essentially the same. The practical consequence is whether the plugin becomes available as a Block, Container, or Box in the editing environment.

Blocks, Containers, and Boxes

• Blocks are mini-templates composed of Containers, Boxes, and other Blocks.
• Containers can contain Blocks, Containers, or Boxes.
• Boxes are terminal HTML output.

A plugin that does not declare a $type does not appear in the Block Editor.

Basic File Structure

Every plugin uses this basic structure:

developerprefix-pluginname/
    plugin.php

The file itself must be named plugin.php. The enclosing folder should use a developer prefix followed by the plugin name, helping avoid naming conflicts and accidental overwrites.

Part 1 — File Headers

The opening comment in plugin.php identifies the plugin to PageMotor before its code is activated.

<?php
/*
Name: Sample Nav Menu
Author: Pearsonified
Description: Output a Nav Menu via Plugin instead of Text Box
Version: 1.0
Requires: 0.1
Class: PM_Sample_Nav_Menu
Docs: https://example.com/docs/
License: MIT
*/

Documented Header Fields

Chris’s January 2026 revision identifies these as the expected core headers:

• Name
• Author
• Description
• Version
• Requires
• Class

He notes that the current implementation may tolerate omission of some descriptive fields, but that should not be treated as a recommended practice.

Optional and Additional Headers

• Docs can produce an information link on the Manage Plugins page.
• Type: Admin designates an Admin-only plugin.
• Production plugins may also include fields such as Updates and License.

Why the Header Exists

The header allows PageMotor to identify available plugins before executing their code. This supports a crucial separation: inactive plugin code should not run, and active plugin code should run only when the framework intends it to.

Part 2 — The Plugin Class

The Class header names the PHP class PageMotor will use when activating the plugin. The header value and PHP class name must match exactly, including case.

class PM_Sample_Nav_Menu extends PM_Plugin {

}

Extending PM_Plugin gives the class the core behavior that makes it a PageMotor plugin.

Core Properties

Every plugin declares a title:

public $title = 'PageMotor Sample Nav Menu';

An HTML-output plugin also declares a type:

public $type = 'box';

The supported template-output types are box, container, and block. In ordinary plugin development, boxes and containers are likely to be the most common.

HTML Output Contracts

A Box plugin provides:

public function html($depth = 0) {
    // Output terminal HTML.
}

A Container plugin provides:

public function container_open($depth = 0) {
    // Output opening container markup.
}

public function container_close($depth = 0) {
    // Output closing container markup.
}

The $depth = 0 parameter allows PageMotor output to preserve readable source indentation.

The Global $motor Object

Plugin methods commonly declare:

global $motor;

Chris describes this object as the key to PageMotor tools and the wider runtime environment. The sample plugin uses it for text sanitation and local-site URL generation. The complete surface of $motor belongs to later research, but its role is already clear: it is the plugin’s gateway into PageMotor services.

Relationship Between Themes and Plugins

Plugins are activated by Themes. Some plugins—especially those with HTML output—may be suitable only for the Admin Theme or only for the front-end Theme. At the time of Chris’s post, PageMotor supported an explicit Admin-only header and anticipated a possible Theme-only provision.

Reference Implementation — EP Dashboard

Kenn Jordan’s EP Dashboard provides a production example that matches the documented structure:

if (!class_exists('PM_Plugin')) return;

class EP_Dashboard extends PM_Plugin {
    public $title = 'EP Dashboard';
    public $dashboard = true;

    public function html($depth = 0) {
        // Render the PageMotor Admin Dashboard.
    }
}

The plugin includes a structured header, extends PM_Plugin, declares a required title, and implements html(). It deliberately omits $type because it is reached through Admin Dashboard delegation rather than being placed into a template Block.

Verified Observation

The EP Dashboard also uses a public property—$dashboard = true—to assert a dashboard capability. Its source comments state that PageMotor 0.10 delegates the Admin Dashboard body to an active plugin asserting that property.

This is strong implementation evidence that plugin properties can advertise framework-recognized roles. It should not yet be generalized into a complete description of all plugin capabilities.

Verified Facts

• Plugins are PageMotor’s primary extension mechanism.
• Plugins may have template-based HTML output or no template-based HTML output.
• A plugin lives in its own folder and uses a file named plugin.php.
• The file begins with metadata identifying the plugin before activation.
• The Class header identifies the PHP class used by PageMotor.
• The class extends PM_Plugin.
• Every plugin declares a $title.
• HTML-output plugins declare a $type of box, container, or block.
• Plugins without $type do not appear in the Block Editor.
• Box output uses html($depth = 0).
• Container output uses container_open($depth = 0) and container_close($depth = 0).
• Plugins are activated in Theme context.

Inference

PageMotor appears to treat plugins as capability providers, not merely feature add-ons. This language is not yet a formal PageMotor term, but it is supported by Chris Pearson’s stated plugin philosophy, Discovery 001, and the production behavior observed in EP Dashboard.

What Is Not Yet Verified

• The complete internal behavior of PM_Plugin.
• The exact discovery and instantiation sequence.
• Which header fields are strictly enforced in the current PageMotor release.
• The complete set of framework-recognized public properties.
• The complete plugin lifecycle from installation through execution.
• How plugin capabilities become visible to PageMotor AI agents.

Design Implications

A new plugin should begin with a capability statement:

After this plugin is active, what new thing should a user, Theme, or authorized AI agent be able to ask PageMotor to do?

The implementation can then be classified as template-output or non-template behavior and expressed through the plugin header, class properties, inherited framework behavior, and appropriate methods.

Evidence Trail

1. Discovery 001 — PageMotor Is More Than a CMS. Established the capability-oriented working hypothesis.
2. Chris Pearson, “Create Your First PageMotor Plugin.” Official creator guidance, originally posted July 12, 2025 and updated January 12, 2026. This is the primary specification source for the plugin mental model, folder structure, headers, class structure, types, output methods, Theme activation, and use of $motor.
3. EP Dashboard plugin.php, Kenn Jordan / ElmsPark. Production reference implementation demonstrating the header, PM_Plugin inheritance, required title, omission of $type for a non-Block-Editor role, dashboard capability declaration, and framework-delegated html() output.

Open Questions

• How does PageMotor discover, validate, and instantiate a plugin?
• What does PM_Plugin provide?
• What is the complete plugin lifecycle?
• What are Valets, and how do they connect a plugin to PageMotor capabilities?
• How do Themes activate and host plugin instances?
• How are plugin Actions and Skills exposed to AI?

Next Discovery

How does a PageMotor plugin live from installation to execution?