Skip to content

DevGuide PluginBasic TemplateTag

Jump to bottom Edit New page
Violet edited this page Dec 6, 2010 · 3 revisions

MDG: Your First Template Tag

Now that you have created your first Melody configuration directive, we need a way to display its assigned value on a blog or website. Hopefully you will find accomplishing this just as simple as before, however, this time we will need to actually create some code.

A Word About Perl

Perl has a reputation for being impossible to read and overly complex. There is a kernel of truth to every stereotype I suppose, but the truth is that Perl need not be complex or scary to the average programmer. In fact, pretty code versus ugly code is more of a reflection of the programmer who wrote it, than it is of the language itself. But be that as it may, the following examples should show that virtually any person who is familiar with PHP or Javascript has the knowledge they need to write enough Perl code to be dangerous; and furthermore, they can write readable Perl in the process.

As always, let's start with the YAML you will need to define your first template tag:

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
config_settings:
  MyImageURL:
	default: http://www.movabletype.com/images/overview-1.jpg
tags:
  function:
    MyImageURL: $Good4Nothing::Good4Nothing::Plugin::tag

There are a couple of things going on here. First the function key defines the type of tag we are creating (we will review the other types of tags later in this manual). A function template tag simply outputs text.

The child element of function is MyImageURL, which defines the name of your template tag. The value of MyImageURL is a reference to a subroutine defined elsewhere in your plugin. When you include this template tag on your website, Melody will invoke the subroutine called "tag" located in the module "Good4Nothing::Plugin" defined by the plugin called "$Good4Nothing" (corresponding to the 'key' used when registering your plugin).

Finally, Melody will support multiple case-insensitive syntaxes in referencing the tag name you create. For example, all of the following are valid ways to refer to the template tag defined above:

  • <mt:MyImageURL>
  • <mt:myimageurl>
  • <$MTMyImageURL$>
  • <$mt:myimageurl$>
  • <mtmyimageurl>

You don't need to worry about defining these yourself. Melody does this for you automatically.

Ok, now, take a deep breath, it is time for some code.

Your Plugin Module

When we discussed "The Basic Structure of a Plugin" we talked about Perl library files that reside in your /path/to/melody/plugins/Good4Nothing/lib directory. These "library files" are the source code of your plugin.

Most simple plugins have only one library file which adheres to this basic naming and packaging convention:

/path/to/melody/plugins/MyPluginName/lib/MyPluginName/Plugin.pm

However, technically this is just convention. Plugins can and do deviate from this and so can yours.

Let's begin:

  1. Create a directory called:

    /path/to/melody/plugins/Good4Nothing/lib/Good4Nothing

  2. In that directory create a file called Plugin.pm and open it in a text editor

  3. Add the following text to your Plugin.pm file:

     # Good for Nothing Plugin for Melody
 # Author: Your Name Here, your.email@address.com
 # Copyright (C) 2010 Your Name Here
 # This file is licensed under the Artistic License, or the same
 # terms as Perl itself.
 package Good4Nothing::Plugin;
 
 use strict;
 sub tag {
     my ($ctx) = @_;
     my $cfg = $ctx->{config};
     return $cfg->MyImageURL;    
 }
 1; # Every module must return true

The first 5 lines are boiler plate. Every Perl module and every source code file should include:

  • a brief description of what the file does
  • a copyright notice
  • the name of the author
  • the license under which the source code is made available.

For brevity's sake, subsequent examples will omit this boiler plate code.

The next two lines define the name of the module, "Good4Nothing::Plugin" and signal to Perl to be more stringent in the syntax it will allow ('use strict'). This is a good thing as it will allow Perl to help enforce in your code better coding practices by surfacing warnings you really should work to eliminate. As a general principle: no program, regardless of language, should issue warnings.

Building plugins to work with a specific version of Melody

When a plugin has been built based on specific features of a major version of Melody (e.g. MT 4.x, MT 5.x, MT 6.x etc), then it is recommended that your Plugin.pm file also include the line:

use MT 4;

This signals to Melody what version of the internal plugin API is being used allowing Melody to adapt more readily to any backwards compatibility issues that may exist between your plugin and the current version of Melody.

Template Tag Handler

The remainder of the Plugin.pm file above defines the meat of your plugin. Let's look at it more closely:

sub tag {
    my ($ctx, $args) = @_;
    my $cfg = $ctx->{config};
    return $cfg->MyImageURL;    
}

Melody passes into every tag handler the current Melody "context." The context contains critical information about the system, including information about the current user, the current request, and the system's configuration. We will use the context to retrieve the value of the MyImageURL configuration directive we declared earlier.

Now that the template tag has been defined you can now use the following tag in your templates to output the value associated with the MyImageURL configuration directive:

<mt:MyImageURL>

We are almost done. If we stop there, you will never succeed in your Jedi training. As Yoda famously said:

"For once you stop documenting your code, forever will you be doomed to forget its function. Relegate your users to confusion you will."

I am pretty sure he said that. You can look it up.

Inline Documentation

Melody is a program written in the Perl programming language and utilizes the inline documentation conventions familiar to most Perl programmers: POD.

I will admit that POD is not the best documentation standard in the world, but it's what we've got. Again, the philosophy of Melody is to keep things simple, despite despite the fact that POD can sometimes be a pain to look at, in Melody we utilize just the minimum to keep it easy to read and to write.

We strongly recommend that every template tag be documented using POD. To make documentation easier to maintain, we recommend that each template tag have its documentation included in close proximity to the tag handler that defines its functionality.

To round out our demonstration of writing your first template tag, we provide a complete example that includes documentation:

# Good for Nothing Plugin for Melody
# Author: Your Name Here, your.email@address.com
# Copyright (C) 2008 Your Name Here
# This file is licensed under the Artistic License, or the same
# terms as Perl itself.
package Good4Nothing::Plugin;
use strict;
use MT 4;

#############################################################
=head2 MyImageURL

This tag outputs the contents of the MyImageURL configuration
directive.

=cut
sub tag {
    my ($ctx,$args) = @_;
    my $cfg = $ctx->{config};
    return $cfg->MyImageURL;    
}
1; # Every module must return true

Without going into too much detail the string of "#" characters is included to make it easier to visually demarcate the beginning of a new tag or function being documented. The =head2 is analogous to <h2> in HTML and signals the beginning of the documentation, and the =cut signals the end of the documentation. Everything else is just documentation.

Congratulations, you have waded all the way into the pool. Now that wasn't so bad was it?

Summary and Conclusion

You have done well, young Padawan. You now possess all of the fundamentals of Melody plugin development to create just about anything. Of course the complexity of your config.yaml and your source code will vary with the scope and ambition of your plugin, but the basic pattern has been established for creating any feature in Melody:

  1. Layout the structure of your plugin.

  2. Create a config.yaml for your plugin that defines its basic structure.

  3. Create a Plugin.pm file that contains the logic, or source code of your plugin.

  4. Document your code.

In subsequent sections of this guide we will discuss additional and more advanced techniques in extending and adding features to Melody.

Continue Reading

 


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

Credits

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