Documentation

Light-weight, fast, simple and powerful!
 
Translations of this page?:

Writing a Plugin

This tutorial attempts to show you how to write a simple plugin for Wolf CMS.

The basics

The first thing to know about writing a new plugin with the Wolf CMS plugin API is that you have enough control to crash the entire application.

In order for Wolf CMS to be a flexible application, it needs to be able to do whatever the developer wants. This is why PHP can be added directly in pages. On the other hand, new plugins still require security to be enforced.

What you need to know about Standards

  1. The names of the plugin directory and the plugin id have to be exactly the same and have to be lowercase_underscored.
  2. Use your own plugin id before each function name, so that you will prevent possible function collisions.
  3. You can use classes, but remember that the plugin will be loaded in both the backend and frontend of Wolf CMS.

A Hello World plugin

Ok! Let’s start with the basics. The best way to learn is by creating a simple plugin which we will call The Hello World Plugin.

  • Create the plugin directory “hello_world”, inside the wolf/plugins directory.
  • Create the index.php file inside the “hello_world” directory.
  • Place the plugin information in the index.php. Here is an example you can use:
Plugin::setInfos(array(
    'id'          => 'hello_world',
    'title'       => 'Hello world!', 
    'description' => 'Allows you to display "Hello World! where you want.', 
    'version'     => '1.0', 
    'website'     => 'http://www.wolfcms.org/')
);
 
function hello() {
    echo 'Hello World!';
}

Do not forget to open the php tag <?php

  • Save the index.php file.
  • Login into the Wolf CMS Administration page and enable the Hello World plugin by clicking on the checkbox.
  • Create a new page and write <?php hello(); ?>.
  • Publish and save the page.
  • View the newly published page and see how the “Hello World!” string from the plugin’s hello() function is displayed.

You can also try adding the same code to a snippet or layout.

These are the basics, but you can see that it is quite simple to add your own GLOBAL functions to Wolf CMS.

More advanced topics

Possible options for setInfos

Here is a fairly complete example of the use of setInfos for a plugin:

Plugin::setInfos(array(
    'id'          => 'hello_world',
    'title'       => 'Hello world!', 
    'description' => 'Allows you to display "Hello World! where you want.', 
    'version'     => '1.0',
    'license'     => 'GPL',
    'author'      => 'Martijn van der Kleijn',
    'website'     => 'http://www.wolfcms.org/',
    'update_url'  => 'http://www.wolfcms.org/plugin-versions.xml',
    'require_wolf_version' => '0.5.0',
    'type' => 'both'
));

Never forget to start your file with the php tag: <?php

The options explained

  • id – required, The name of the plugin directory. Always lowercase, preferably one word otherwise use underscores.
  • title – required, The plugin name as it shows up in the administration screen.
  • description – required, Displayed in the administration screen.
  • version – required, A string representing the version number. Preferably in an x.y.z format.
  • license – required, The license which applies to the plugin. This should always be compatible with the Wolf CMS core license.
  • author – Your name.
  • website – The url of your site.
  • update_url – Should point to an xml file containing information about the latest version of your plugin. See this document for the xml file’s structure.
  • require_version – The minimum version of Wolf CMS required for your plugin to function properly.
  • type – Needs to be included when the plugin is intended to work in the front-end of the website as well instead of just the admin section,

Adding javascript files to your plugin

Sometimes you will need to be able to add external javascript files to the generated page an end-user sees. Currently there are two options:

  1. Add your javascript code to an automatically included file.
  2. Specifically add one or more javascript files. (backend only)

Using the automatically included file

Wolf CMS automatically detects the presence of and includes a javascript file using the naming convention: .js

So if your plugin is called “tinymce”, the file that automatically gets included is: “tinymce.js”

Specifically adding one or more files

This function is currently only available for the backend. But since most plugins will generally be for the backend, this should not be a huge problem. To add a javascript file, simply use the following code in your plugin’s index.php file:

Plugin::addJavascript('myplugin', 'myCustomJavascript.js');

or:

Plugin::addJavascript('myplugin', 'asubdirectory/myCustomJavascript.js');

Adding filters to your plugin

First of all, you need to know that a filter is only used in the backend of Wolf CMS. It will never be loaded in the frontend of the website. A filter is intended to provide content editors and the like with a an easy Wiki/WYSIWYG/WYSIWYM style editor. The exact style varies between filter implementations.

A filter can be linked to a toolbar like the Markdown and Textile Filter, that extends the Control.TextArea.ToolBar. Take a look at the markdown.js file in the Markdown plugin. It is easy to create your own ToolBar.

To add your filter to the filters list, you have to call Filter::add and pass the Plugin Id and the filter file path.

Filter::add('hello_world', 'hello_world/filter_hello_world.php');

In your filter_hello_world.php file you need to code the HelloWorld class (camelized name of hello_world); this is the convention used. When a page part filter is set to your filter, the function applied will be called with the text of the part in parameter. Let’s create a simple HelloWorld filter.

class HelloWorld {
    function apply($text) {
        return "<p>Hello World!</p>\n\n".$text;
    }
}

Never forget to start your file with the php tag: <?php

This filter will return the text prefixed by a Hello World! paragraph.

 
tutorials/plugin.txt · Last modified: 2012-11-16 14:09 by David
 
Except where otherwise noted, content on this wiki is licensed under the following license:GNU Free Documentation License 1.2
Copyright 2010 wolfcms.org / design by yello studio / Wolf CMS Inside