Writing a Plugin - advanced topics
First off, if you haven’t read through the page Writing a plugin – the basics yet, please do so now.
What you need to know about Standards
- The names of the plugin directory and the plugin id have to be exactly the same and have to be lowercase_underscored.
- Use your own plugin id before each function name, so that you will prevent possible function collisions.
- You can use classes, but remember that the plugin will be loaded in both the backend and frontend of Frog CMS.
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' => 'AGPL',
'author' => 'Philippe Archambault',
'website' => 'http://www.madebyfrog.com/',
'update_url' => 'http://www.madebyfrog.com/plugin-versions.xml',
'require_frog_version' => '0.9.3'
));
Note: 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 Frog 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_frog_version – The minimum version of Frog required for your plugin to function properly.
Adding javascript files to your plugin
Sometimes you will need the be able to add external javascript files to the generated page an end-user sees. Currently there are two options:
- Add your javascript code to an automtically included file.
- Specifically add one or more javascript files. (backend only)
Using the automatically included file
Frog automatically detects the presence of and includes a javascript file using the naming convention:
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:
addJavascript('myplugin', 'myCustomJavascript.js');
or:
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 Frog 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;
}
}
Note: never forget to start your file with the php tag: <?php
This filter will return the text prefixed by a Hello World! paragraph.
