Create A Plugin

- Create A Plugin

Create A Plugin

Caveat: This document was authored by someone who has not written a plugin yet. It is his effort to use a plugin to figure out and document how plugins are written. Please correct any inaccuracies that you find.

Introduction

In this document, pseudo names will be used that you should replace with names that you create. These self explanatory names are:

your_project
plugin_name – plugin_name will, in some instances, be part of a longer name.

Remember that to “work”, a plugin needs to not only execute correctly (including being tested) as any code does, but it must be able to be installed and uninstalled correctly. Plugins need to be written in the directory

your_project/app/vendors/plugins/plugin_name

This will be abbreviated to plugin_root. (Note that Rails plugins are in a different location: your_project/vendors/plugins/plugin_name.)

Structure

Following is the directory structure and a list of the basic files for your plugin. We have deleted some lines required by some, but not all, plugins so that the essence of a plugin may be more easily seen. This document was created using the Admin plugin as an example. You may want to reference it. (Suggestion:

Create a new project.
Install the Admin plugin.
Change to the your_project/app/vendors/plugins directory.
Execute
```
tree
```
Examine the contents of the files, especially the ones in uppercase.

The line numbers reference list items that explain the entry:

   .
   `-- plugin_name
 1     |-- LICENSE
 2     |-- MAINTAINERS
 3     |-- README
 4     |-- TODO
 5     |-- generators
       |   `-- plugin_name_scaffold
       |       |-- USAGE
       |       |-- plugin_name_scaffold_generator.php
       |       `-- sintags_templates
       |           `-- <files>
 6     |-- installer
   I   |   |-- plugin_name_files
       |   |   |-- app
       |   |   |   |-- controllers
       |   |   |   |   |-- plugin_name
       |   |   |   |   |   `-- <files>
       |   |   |   |   `-- plugin_name_controller.php
       |   |   |   |-- helpers
       |   |   |   |   |-- plugin_name
       |   |   |   |   |   `-- <files>
       |   |   |   |   `-- plugin_name_helper.php
       |   |   |   |-- installers
       |   |   |   |   `-- plugin_name_plugin_installer.php
       |   |   |   |-- models
       |   |   |   |   `-- <files>
       |   |   |   `-- views
       |   |   |       |-- plugin_name
       |   |   |       |   |-- <model_name>
       |   |   |       |   |   `-- <files>
       |   |   |       `-- layouts
       |   |   |           `-- plugin_name.tpl
       |   |   |-- public
       |   |   |   |-- images
       |   |   |   |   `-- plugin_name
       |   |   |   |       `-- <files>
       |   |   |   `-- stylesheets
       |   |   |       `-- plugin_name
       |   |   |           `-- <files>
       |   |   `-- test
       |   |       |-- fixtures
       |   |       |   |-- app
       |   |       |   |   |-- installers
       |   |       |   |   |   `-- plugin_name_plugin_installer.php
       |   |       |   |   `-- models
       |   |       |   |       `-- <files>
       |   |       |   `-- data
       |   |       |       `-- plugin_name
       |   |       |           `-- extensions.yaml
       |   |       `-- unit
       |   |           `-- app
       |   |               `-- models
       |   |                   `-- <files>
  II   |   `-- plugin_name_installer.php
 7     |-- makelos
       `-- test
           `-- plugin_name.php

Explanation of Structure Entries

LICENSE – This file should contain the text of the GNU LESSER GENERAL PUBLIC LICENSE which you may obtain from any other Akelos plugin. The LICENSE of the Admin plugin is http://svn.akelos.org/plugins/admin/LICENSE.
MAINTAINERS – This file should contain a list of the authors and maintainers, beginning with your name, the author in the format
```
name, email and title
```
The title should describe your function with regard to this plugin. For example:
```
 Bermi Ferrer Martinez <bermi-a.t-akelos-d.ot-co.m> Lead developer 
```
README – This should contain the following sections:
- A description of the plugin
- Installation instructions
- Usage instructions
- Future plans for the plugin, if any
TODO – A list of features / bug fixes to be addressed in the future
generators/ – A generator does not copy code. It uses PHP code to generate new PHP code in the Akelos context. Generators in this section are extensions of those found in the Akelos source at lib/utils/generators. Below this directory entry is an example of scaffold code that is used to create new scaffolding. Generators are not required in every plugin.
installer/
1. plugin_name_files/ – These are the files and directories that are to be copied into the main part of the project. Not all that are shown here need to be in every plugin. The directory structure under plugin_name/installer/plugin_name_files determines where the files will be copied. The files in plugin_root/plugin_name/installer/plugin_name_files/app/controllers/ will be copied into your_project/app/controllers/. One thing to note is that you should create plugin_name as a new directory under each existing directory, i.e. because “controllers” is a subdirectory that exists in the app directory, by writing the plugin so that the installation creates your_project/app/controllers/plugin_name/ the chance of a file collision during installation is eliminated.
2. plugin_name_installer.php – This file installs the plugin. It is called by the makelos file (see below). It has the following functions:
  - up_1 – This checks for file collisions, copies and modifies files and runs the migration program plugin_root/installer/plugin_name_files/installers/plugin_name_plugin_installer.php. This file is the same migration that you would write for any project. It creates and drops tables and sets defaults, etc.
  - down_1 – Uninstalls the plugin migration
makelos (make akelos) – This PHP program is a “make” type file for doing things with the plugin. A good example is the one written for the admin plugin, which can be found at http://svn.akelos.org/plugins/admin/makelos. In your copy of this file, replace the string “admin” with the name of your plugin. Make any other changes necessary for your plugin. Note that makelos needs a file that you will write in plugin_name/installer/plugin_name_installer.php. Use the following syntax to perform the indicated functions on your plugin:
- makelos install
- makelos uninstall
- makelos test (array_of_options)
- makelos help – As written, this function will just return the names of these functions.