Quick Start

In Typemill, the PHP file houses your plugin's business logic. While you might also write business logic with Vue.js in many cases, you will always start with PHP.

• Quick Start
  • Minimal Plugin
  • Namespace
  • Extend the Typemill Plugin Class
  • The Typemill Event System
  • Subscribe to Events
  • Methods
  • Event Arguments
  • Add Routes
  • Add Middleware

Minimal Plugin

The basic PHP file of your plugin must share its name with the plugin folder. For example:

/myplugin
  - myplugin.php

A minimal plugin class subscribes to at least one event and contains one subscriber method:

<?php

namespace plugins\myplugin;

use \typemill\plugin;

class myplugin extends plugin
{
    public static function getSubscribedEvents()
    {
        return [
            'onPagetreeLoaded' => 'onPagetreeLoaded'
        ];
    }

    public function onPagetreeLoaded($navigation)
    {
        // do something with the $navigation
    }
}

The basic tools and concepts that you need for a plugin are namespaces, inheritances, events, methods, routes and middleware.

Namespace

All plugins use the namespace plugins\, followed by the name of your plugin.

Extend the Typemill Plugin Class

Each plugin extends the base plugin class \typemill\plugins.

<?php

namespace plugins\myplugin;

use \typemill\plugin;

class myplugin extends plugin
{
}

When a class extends another class, it means that the new class automatically has access to the properties and methods defined in the parent class (inheritance). You can check all the properties and methods that are available for your plugin in the method overview.

The Typemill Event System

The Typemill plugin system adheres to the principles of event-driven development, utilizing the event dispatcher from Symfony. If you're familiar with Symfony's event dispatcher, you'll find the Typemill system intuitive.

If you are not familiar with events, then take a minute to grab the concept. When Typemill gets a request to render a page, it loads the settings, loads the plugins, loads the themes, creates the navigation, gets the page content, and finally renders the page. For each step, it fires an event and sends data with the events. Plugins can subscribe to these events, read, manipulate, and often return the manipulated data to Typemill.

For example, if Typemill has created the navigation, it fires the event "onNavigationLoaded" and sends the navigation data. If a plugin has subscribed to this event, it can read the navigation, change the navigation, and return it to Typemill.

Subscribe to Events

Every plugin must have a public static method called getSubscribedEvents(). It returns an array with events as keys, and plugin methods as values.

<?php

namespace plugins\myplugin;

use \typemill\plugin;

class myplugin extends plugin
{
    public static function getSubscribedEvents()
    {
        return [
            'onPagetreeLoaded' => 'onPagetreeLoaded'
        ];
    }

    public function onPagetreeLoaded($navigation)
    {
        // do something with the $navigation
    }
}

You can listen to several events in your plugin class:

public static function getSubscribedEvents()
{
  return [
        'firstEvent' => 'firstMethod',
        'secondEvent' => 'secondMethod'
    ]
}

You can also add several methods to a single event, and arrange these methods by priority:

public static function getSubscribedEvents()
{
    return array(
        'firstEvent' => array(
            array('firstMethod', 10),
            array('anotherMethod, 1)
        ),
        'secondEvent' => 'secondMethod'
    )
}

The rule for the order is pretty simple: The higher the order, the earlier the call. You can also use negative numbers like -10 to give a method call a really low priority.

Methods

You can name the methods of your plugin class however you want. Many people give their methods the same name as the events. This way you can easily see which method is called by which event; but it's a matter of taste:

public static function getSubscribedEvents()
{
    return array(
        'onSettingsLoaded' => 'onSettingsLoaded'
    );
}

public function onSettingsLoaded($settings)
{
    // do something with the $settings
}

Within your methods, you can write your business logic.

Event Arguments

All events pass some arguments into your method, and in many cases they also pass data that you can use or manipulate (like the $navigation in the example above). You can find all the details in the event overview.

Add Routes

Sometimes you want to add a new route, for example, to provide a new API endpoint, to receive and process data from a public form, or to add a new item to the system navigation and inject a new Vue application.

You can add as many new routes as you want in your plugin. Read more about it here.

Add Middleware

In some cases, you may want to add middleware. The concept of middleware is widespread but a bit harder to grasp. Please refer to the chapter about middleware if you want to know more details.