-
Notifications
You must be signed in to change notification settings - Fork 0
Addon Dev – Plugin Pages
Typesetter plugins can hook into the CMS in many ways but mostly they will generate some output. This can be so-called Gadgets, plugin-based custom section types, plugin-generated Special Pages or Admin Pages. First of all, we will cover the latter two…
A 'Special_Link' section in Addon.ini will tell Typesetter that the plugin generates a Special Page. This page will be available once the plugin is installed and can be added to a menu or linked otherwise. Plugins can generate multiple Special Pages. For now, we limit ourselves to one.
[Special_Link:MyFirstPlugin_Special_Page]
label = 'My First Plugin - Special Page'
script = Special.php
ini sections are defined in square brackets. The 'Special_Link:' part will tell Typesetter that the following keys are about a Special Page, 'MyFirstPlugin_Special_Page' defines the page slug (URL part). The page slug has to be unique and must not already be used by an existing page or a different plugin.
The value 'My First Plugin - Special Page' will be the page label. Page labels are used in menus and as part of the <title> tag of the <head> section of the page. The label doesn't have to be unique and may be arbitrary text. But do yourself a favor and avoid the characters { } < > # and ? (and also keep it below 40 characters).
The value of the 'script' key tells Typesetter which PHP script to load when the page is displayed. Its file path is relative to the plugin directory.
Create a new Special.php file and add a few lines of PHP:
<?php
defined('is_running') or die('Not an entry point...');
echo '<h2>A Special Page</h2>';
echo '<p>This page was created by my first Typesetter plugin.</p>';
- Always use
<?phpstarting tags in your scripts. Do not use short<?tags – they may or may not work elsewhere and are considered deprecated for good reasons.- The line
defined('is_running') or die('Not an entry point...');ensures that the script can only be called by Typesetter and cannot be accessed directly. It is recommended to always include this line at the top of PHP scripts inside Typesetter context, unless you have good reasons not to.- Always omit the closing
?>PHP tag at the end of the file unless you want to output plain text/HTML afterwards.- Always consider file names case sensitive. If you are developing on a (local) Windows server, you won't notice case mismatches – but you certainly will, once your plugin has to work on Linux, Apple OS X or other Posix systems.
Admin Links will define pages that are only accessible for logged-in users (AKA 'Admins'). You will normally use such Admin Pages for plugin configuration purposes but of course they may also contain other things. An Admin_Link section is defined similar to Special_Link.
[Admin_Link:Admin_MyFirstPlugin]
label = 'MyFirstPlugin Settings'
script = Admin.php
We already know how to define a new ini-section. Now we use 'Admin_Link:Admin_MyFirstPlugin' inside the square bracktes. The 'label' and 'script' keys are as we already know them.
Again, create a new Admin.php file and add some PHP:
<?php
defined('is_running') or die('Not an entry point...');
echo '<h2>My First Plugin » Settings</h2>';
echo '<p>This is the configuration page of my first Typesetter plugin. </p>';
Ready to install
At this point you may already install your plugin via Typesetter's Admin Toolbox → Plugins → Manage → Available → My First Plugin. Of course this plugin yet doesn't do much and the Admin Page won't actually have configuration options.
You may always change the code of installed plugins. Sometimes you will need to click the 'Upgrade' link in the Options section of your plugin on the Plugins → Manage page in order to activate new parts and features. There are also cases where un-installation and re-installation is required, e.g. when you want to change the plugin name.