Skip to content

DevGuide PluginBasic BuildFirstPlugin

Jump to bottom Edit New page
RickBychowski edited this page Jun 8, 2011 · 2 revisions

MDG: Building Your First Melody Plugin

So you want to build a plugin for the Melody Publishing Platform do ya? Awesome. This guide will be one of your first steps in familiarizing yourself with the process. One of the first questions a developer asks is "what will the API let me do?" Or in other words, what can you build as a plugin?

Truthfully, the answer to that is simple: virtually anything. For now, just take our word for it. Because right now, you are just getting started and shouldn't have to worry about that kind of complexity. So, let's begin by wading into the shallow end of the pool. Then as we progress through this guide we build your skills and confidence up so that you will feel comfortable at the deeper end of the pool.

One of things we hope you will see is just how easy it can be to write a plugin. Melody has been designed and continues to evolve in such a way that it tries to limit the amount of programming knowledge you need in order to develop a plugin. The use of Perl is sometimes unavoidable, but as we understand more about the patterns developers follow to build their plugins, the Melody community will adapt to making those patterns easier to replicate using less and less code. Themes, for example, are a type of Melody plugin that require absolutely no Perl.

If you are interested in building a theme for Melody, please consult the MTDG - Melody Theme Designer Guide.

The following section will introduce you to how Melody plugins work. First we will discuss the basic syntax of the heart of any Melody plugin: the configuration file, or config.yaml file. Then we will create the simplest plugin you could possibly write and slowly add to it, introducing you to simple concepts as we go.

  • Introduction to the Melody Registry
  • A YAML Primer
  • Registering Your Plugin: Basic Plugin Metadata
  • Adding Your First Configuration Directives
  • Adding a Simple Template Tag
  • Adding a Conditional Template Tag
  • Adding a Template Tag Modifier

The Melody Registry: What it is, and how it works.

The heart of any Melody plugin and in Melody itself is the Melody Registry. Perhaps "heart" is not an apt metaphor. A more accurate comparison might be to the "backbone." That is because the registry provides the rough outline or skeleton of a plugin by declaring all the template tags, configuration directives, objects, callbacks, and all of its other features as well. From that skeleton we attach the muscles that make things move using Perl.

This skeleton is a expressed in a very simple syntax known as YAML (see the YAML Primer later on in this section) and is found in a single file in your plugin named config.yaml. Within the config.yaml file developers express the basic capabilities their plugin exposes in outline form. Let's look at a simple example:

Example config.yaml File

name: Fluid App
id: FluidApp
author_link: http://www.majordojo.com/
author_name: Byrne Reese
description: This plugin provides enhanced support for Fluid for Mac OS X.
version: 0.90
plugin_link: http://www.majordojo.com/projects/mt-fluid-app.php

applications:
    cms:
        methods:
            fluid_update: $FluidApp::FluidApp::Plugin::cms_update
callbacks:
    MT::App::CMS::template_source.header: $FluidApp::FluidApp::Plugin::xfrm_hdr

Don't worry if the above example does not make any sense yet, it is provided simply to introduce you to the syntax or structure of a config.yaml file. This example actually comes from a real Melody plugin - one that provides an integration with the Fluid Application for Mac OS X.

It may not be evident to a non-technical person, but the config.yaml file above does not define behavior, it simply declares the types of behavior this plugin will exhibit and then points to methods within the plugin's source code where that behavior is defined.

A Cumulative Registry

An important fact in working with your plugin's config.yaml is that you can add as many elements discussed in this guide into a single config.yaml file. In theory you could merge all of the examples discussed in this guide and produce a single uber-example.

Learning YAML

See: MDG: a YAML Primer for Melody Developers

Registering Your Plugin: Basic Plugin Metadata

You now know what a plugin is, you know what the registry is and you know the basic syntax of YAML. It is time for you to write your first plugin. So, without further ado:

  1. Create a directory called /path/to/melody/plugins/HelloWorld.

  2. In that directory create a file called config.yaml and open it in a text editor.

  3. Add the following text to your config.yaml file:

     name: Good for Nothing Plugin for Melody
 id: Good4Nothing
 author_link: http://www.yourwebsite.com/
 author_name: Your Name Here
 description: This plugin is an example plugin for Melody.
 version: 1.0

  4. To see your new plugin, login to Melody and navigate to: System Overview > Plugins. You should see "Good for Nothing Plugin for Melody" listed there.

TODO: screenshot

Congratulations, you just wrote your first Melody plugin, and you didn't even have to write any code! Wow. Yeah, I knew you would be impressed.

So what does this plugin do?

Good question. It does absolutely nothing, just as the name implies. But let's review what you just did.

The above config.yaml file told Melody the basics of what it needed to know about your plugin to list it properly among other plugins in your installation. Here is a brief overview of the registry keys used above, as well as some additional keys you might be interested in using:

  • name - The display name of the plugin.
  • id - A unique identifier for this plugin used when looking up this plugin's data in the registry. It is also used when referring to handlers within the plugin (optional - when left unspecified, the plugin's directory name will be used).
  • key - The string used by Melody when storing and retrieving stored via MT::PluginData (optional - when left unspecified, the plugin's ID will be used).
  • author_link - The URL to the primary author.
  • author_name - The name of author or authors.
  • description - A brief one or two sentence of what this plugin actually does.
  • version - The current version of the plugin.
  • plugin_link - The URL to the plugin's homepage.

But who wants a plugin that does nothing? Time now to wade a little deeper into the pool.

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