Skip to content

devguide pluginbasic basicstructure

Jump to bottom Edit New page
Hiranyaloka edited this page Jun 25, 2011 · 11 revisions

MDG: Basic Structure of a Plugin

All Melody plugins are organized by a simple set of files and directories. These files and directories contain all of the static files, templates and application code needed for the plugin to operate.

A plugin can typically be described most commonly by the following four primary components:

  • A config.yaml or plugin configuration file.
  • A collection of Perl library files. Note: many theme plugins will not have Perl files.
  • A set of templates that govern the look and feel of pages within your plugin.
  • A set of static images, javascript and css files used within your plugin templates, or by the published blog.

This translates into the following structure on your file system:

/path/to/melody/plugins/PluginName/config.yaml
/path/to/melody/plugins/PluginName/lib/*
/path/to/melody/plugins/PluginName/tmpl/*
/path/to/melody/plugins/PluginName/static/*

Other Common Directories

External or 3rd Party Library Files or Modules

If your plugin relies on 3rd party Perl modules or libraries then it is recommended that they be packaged in the following directory:

/path/to/melody/plugins/PluginName/extlib/*

Tip: When should I package 3rd party libraries with my plugin?

To make installation of your plugin easier upon your users, you may want to package any prerequisites directly within your plugin. However before you do that, make sure of the following:

  • The module's license allows you do to so. If the 3rd party module uses the "Artistic" license (often phrases as "the same licenses as Perl itself") then you can safely include it. The same is true for modules that use the BSD and LGPL license provided that you do not modify the source code of the module. Perl modules that utilize the GPL license is also permissible.

  • The module does not require compilation. If the third party library contains .xs files or .c files then your users must install the module independently.

PHP and Dynamic Publishing Files

Plugins that define template tags should also provide PHP versions of those tags so that they are compatible with blogs and templates configured for dynamic publishing. These files should be placed within the following directory within your plugin:

/path/to/melody/plugins/PluginName/php/*

Naming and Packaging Conventions

  1. Use spaces in your plugin's display name. Developers like symmetry, who doesn't? But maintaining symmetry between the display name of your plugin and the file system is not ideal from a searchability and findability perspective.

    • HelloWorld - bad
    • Hello World - good

  2. Do not prefix the name of your plugin with "MT" or "Melody" It is a foregone conclusion that your plugin works with Melody. If you wish to indicate this explicitly, append the phrase "for Melody" to your plugin's display name, or use it as your plugin's description. Examples:

    • MTHelloWorld - bad (it uses the "MT" prefix)
    • HelloWorld - bad (no spaces)
    • Hello World - good
    • Hello World for Melody - good
    • Hello World, a plugin for Melody - good

  3. Use mixed case directory names. The use of all lowercase letters in the structure of your plugin is generally not recommended. What is recommended is to capitalize the first letter of the plugin, and the first letter of each distinct word.

    • plugins/helloworld/ - bad
    • plugins/helloWorld/ - bad
    • plugins/MTHelloWorld/ - bad (see note above: the use of the "MT" prefix is not recommended)
    • plugins/HelloWorld/ - good

  4. Include a README file. A PLUGIN_NAME-README.txt file should be placed in the root of your plugin's archive that provides adequate documentation on the installation and usage of your plugin.

  5. Include a LICENSE file. A PLUGIN_NAME-LICENSE.txt file should be placed in the root of your plugin's archive that contains the text or a reference to the license associated with your plugin.

Plugin Packaging: Makefile.PL and Plugin Manifests

Once your plugin is ready for distribution, you will need to package it up into a single file, a zip file or a "tarball" (a .tar.gz file common among unix users) so that your users can easily download it.

Even though you have a choice between .tar.gz and .zip files we recommend only producing .zip files as in this day and age, zip is supported almost everywhere.

To create a zip file, you first need to produce two simple files: a Makefile.PL file and a MANIFEST.SKIP file. These files produce an automated way for you to reliably create a zip file. Here are some examples:

Example Makefile.PL - Simple

use ExtUtils::MakeMaker;
WriteMakefile(
    NAME            => "My Plugin's Display Name",
    VERSION         => '1.1',
    DISTNAME        => 'MyPlugin',
);

Example Makefile.PL - Advanced

The following Makefile.PL file has the advantage of not requiring you to update the version number within it each time you make a release. It does however require that you have YAML::Any installed.

use YAML::Any qw(LoadFile);
my $file = "plugins/MyPlugin/config.yaml";
my $version = LoadFile($file)->{version} ||
    die "No version found in $file";
use ExtUtils::MakeMaker;
WriteMakefile(
    NAME            => "My Plugin's Display Name",
    VERSION         => $version,
    DISTNAME        => 'MyPlugin',
);

Example MANIFEST.SKIP

# version control
\bCVS
(^|/)\.

# CPAN chain files
^MANIFEST
^Makefile
^META.yml$
^blib/
~$

# packages
\.zip$
\.tar\.gz$

Creating a zip file for your plugin

Note: If you are using GitHub, all that is necessary (after configuring Makefile.PL and MANIFEST.SKIP as described above) is to tag the commit and push the tag to github. Github will magically create the zipped file for you (in the "downloads" section of your repo). For example:

prompt> git tag -a v1.0.1 -m "MyPlugin first stable release"
prompt> git push --tags

And we take you back to the tutorial...

Provided you have created a Makefile.PL and MANIFEST.SKIP file, the following sequence of commands will quickly and easily produce a zip file of your plugin. The zip produces will be clean - there will be no .~ files, or .svn files, or any other artifacts of development. The zip file will automatically have the version number of the plugin embedded within it to make it easy for your users to differentiate between older and newer builds.

prompt> cd src/PluginName
prompt> perl Makefile.PL
prompt> make manifest
prompt> make zipdist

Storing Your Plugin in Source Control

To make it easier for other Melody developers to collaborate on plugins you author, but also to make packaging and maintenance easier for yourself, the following conventions have been adopted by the community at large in regards to how you should store and manage your plugins in github, a popular and free source code control system.

/path/to/github/mt-plugin-MyPlugin/plugins/MyPlugin/config.yaml
/path/to/github/mt-plugin-MyPlugin/README.md
/path/to/github/mt-plugin-MyPlugin/Makefile.PL
/path/to/github/mt-plugin-MyPlugin/MANIFEST.SKIP
/path/to/github/mt-plugin-MyPlugin/plugins/MyPlugin/lib/*
/path/to/github/mt-plugin-MyPlugin/plugins/MyPlugin/tmpl/*
/path/to/github/mt-plugin-MyPlugin/plugins/MyPlugin/static/*

The pattern, if not immediately evident, is to mirror the file structure of Melody itself. That way users wishing to install your plugin can follow these simple instructions and trust that all of your plugin's files will wind up in the right place:

prompt> cp MyPlugin-1.0.zip /tmp/
prompt> cd /tmp/
prompt> unzip MyPlugin-1.0.zip
prompt> cp -a MyPlugin-1.0/* $MELODY_HOME

Continue Reading

 


Questions, comments, can't find something? Let us know at our community outpost on Get Satisfaction.

Credits

  • Author: Byrne Reese
  • Edited by: Violet Bliss Dietz
Add a custom footer
Add a custom sidebar
Clone this wiki locally