DevGuide

MDG - Melody Developer Guide

Welcome to the Melody Developer Guide for those who wish to extend Melody's core platform with custom functionality, user interfaces and other components. The primary method of extensibility is via plugin. This guide is appropriate for developers of all skill levels, but does require a least a passing knowledge of Perl although you will find that a lot can be accomplished in Melody with very little, or at least a very intuitive use of the Perl programming language.

This guide is divided into several main sections, and depending upon your familiarity with both Perl and Melody, you may want to start at the beginning or jump to another section. Those sections are:

1. Introduction to Plugins - answers the most basic question: "what is a plugin?" and explains how a plugin is packaged for distribution as a Melody plugin.

2. Plugin Basics: Building Your First Melody Plugin - you'll implement a very simple plugin with a handful of features, learn about the Melody config.yaml registry, and find out about some good coding practices that should be used in Melody plugin development.

3. Taking Your Plugin to the Next Level - learn about each of the features Melody exposes through the registry, including configuration directives, text filters, template tags, ping servers, and more.

4. Advanced Developer Topics - Obtain Melody Developer nirvana by mastering callbacks, objects, database interaction and performance optimization.

Using this Guide

Often this guide needs to refer to a path on the file system that is relative to Melody's home directory. Melody's home directory, also known or referred to by the phrase "MT_HOME" or "$MT_HOME," is where Melody is installed. Because Melody can be installed in numerous locations depending upon personal preference, operating system conventions, this guide (as well as most examples online) utilizes the following conventions to refer to the path where you can find Melody's files:

• /path/to/mt

Example

Let's assume for a moment that you have installed Melody into the following directory on your web server:

/var/www/vhosts/www.somedomain.com/cgi-bin/mt

If this is true, then you should find the following files on your filesystem:

• /var/www/vhosts/www.somedomain.com/cgi-bin/mt/index.cgi
• /var/www/vhosts/www.somedomain.com/cgi-bin/mt/config.cgi
• /var/www/vhosts/www.somedomain.com/cgi-bin/mt/lib/MT.pm
• And many more...

So using, that as the basis for this example, if this guide refers to the path:

/path/to/mt/lib/MT/App/CMS.pm

Then that path can be translated into the following path on your filesystem:

/var/www/vhosts/www.somedomain.com/cgi-bin/mt/lib/MT/App/CMS.pm

Also, this guide makes frequent reference to your Plugin.pm file. The Plugin.pm file refers to the main library file (located in /path/to/mt/lib/PluginName/) that contains all of the application logic and Perl code for your plugin. Technically this file can be named whatever you want provided that it is a valid Perl module. For the purposes of consistency and the integrity of the examples in this guide, we use and refer to this file as "Plugin.pm".

Introduction to Plugins

Melody's Plugin API provides developers with the ability to extend Melody's core platform with additional functionality. Developers use this API to create "plugins," which can be as simple as providing a template tag for designers to use in their templates, or as complex as providing an entire suite of capabilities. Plugins can also function as an entire stand alone application that runs on top of the Melody Publishing Platform.

The following sections will introduce developers unfamiliar to Melody and its conventions to the structure of a plugin, how it should be packaged and delivered to users, and finally how you can list it in the directory to help others find and install it.

• MDG: Basic Structure of a Plugin
• MDG: A YAML Primer for Melody Developers

Plugin Basics: Building Your First Melody Plugin

Next we jump into the shallow end of the pool and explore the basics of building your first plugin. It's not difficult. Just be sure you pay attention to the spacing requirements of YAML and that blank line at the end.

• MDG: Building Your First Melody Plugin
• MDG: Your First Config Directive
• MDG: Your First Template Tag
• MDG: Debugging Melody and Melody Plugins

Taking Your Plugin to the Next Level

With the above basics behind us we can begin tackling problems and issues that you are much more likely to face in the real world. Not only are we going to revisit some of the topics previously discussed in order to cover them in much greater detail, but we are going to introduce entirely new concepts that range across the entire spectrum of Melody's capabilities.

Each topic will follow a simple pattern in its example: a config.yaml excerpt and a code sample in Perl that is meant for your Plugin.pm file. With a more complete view of the capabilities of Melody's registry we will then dive much deeper into Melody's Perl API, exploring its many interfaces and capabilities.

Here are the topics you can explore in more detail:

• MDG: Configuration Directives
• MDG: Creating Template Tags - A Complete Reference
• MDG: Creating Template Tag Modifiers
• MDG: Creating Text Filters
• MDG: Custom OpenID Authentication Drivers
• MDG: Custom OpenID Login Screens
• MDG: Ping Servers
• MDG: Setting Up Scheduled Tasks
• MDG: Creating a Custom Spam or Junk Filter
• MDG: Upgrade Functions
• MDG: Custom and Pluggable Rich Text Editors - Melody's ArcheType Framework

Advanced Topics

But wait, there's more! Advanced Melody applications and plugins make greater use of Melody's native Perl API, and rely on a greater familiarity with programming fundamentals and design patterns. At some point you may encounter instances where you need to perform more advanced tricks, like subverting Melody's default behavior. While not necessarily something we recommend, it is sometimes necessary to achieve the user experience you envision for your product.

In this section we introduce a number of topics including how to listen for and respond to events fired by Melody, how to create, load, save and delete objects stored in Melody, how to create your own Melody objects and extend existing Melody objects, and how to implement key interfaces like Melody's extensible authentication framework.

• MDG: Advanced Registry Tips
• MDG: Introduction to Events and Callbacks
• MDG: Melody Callback Reference
• MDG: Introduction to Custom Objects
• MDG: Manipulating Objects - Saving, Loading and Deleting Data
• MDG: Creating "Junkable" Objects
• MDG: Building Scorable Objects
• MDG: Creating Revisionable Objects
• MDG: Building Taggable Objects
• MDG: Using AJAX in Plugins

Additional References

• MT::Object Reference - an even more in-depth look at custom objects in Melody
• Application (API) Development in Melody

Advanced System Administration

Here are some system administration and performance tuning references Melody developers may want to consult.

• MSAG: Custom Background Task Handlers
• MSAG: Monitoring and Logging Plugin and Application Performance
• MSAG: The Ultimate Guide to Template Caching
• MSAG: Using Melody's "Publish Queue"
• MSAG: Using Melody's Revision System

 

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