root/trunk/HelloWorld/plugins/HelloWorld/HelloWorld.pl @ 674

package MT::Plugin::HelloWorld;
#
# This is a modified version of the code listed in "Hacking Movable
# Type" by Allen, Choate, Hammersley, Haughey and Raynes, in chapter
# 10: Writing Plugins.  
#
# If you spot an inaccuracy or improvement in the context of The Book
# or PluginManager requirements, patches are welcome!
#
use strict;
use warnings;

use MT;
use MT::Plugin;
use MT::Template::Context;

use base 'MT::Plugin';

our $plugin;
our $VERSION = '0.5';
MT->add_plugin($plugin = __PACKAGE__->new({
        name            => "Hello World",
        version         => $VERSION,
        description     => "Enables friendly greetings.",
        author_name     => "Ima Hacker",
        author_link     => "http://example.com/",
    template_tags => {
        'HelloWorld' => \&HelloWorld,
        'HelloWorldGreeted' => \&HelloWorldGreeted,
    },
    container_tags => {
        'HelloWorldContainer' => \&HelloWorldContainer,
    },
    conditional_tags => {
        'HelloWorldIfNameProvided' => \&HelloWorldIfNameProvided,
    },
    global_filters => {
        'to_uppercase' => \&to_uppercase,
    },
}));


sub HelloWorld {
    my($ctx, $args) = @_;
    my $name = _get_name($ctx, $args);
    return "Hello $name!";
}

sub HelloWorldContainer {
    my($ctx, $args) = @_;
    my $builder = $ctx->stash('builder');
    my $tokens = $ctx->stash('tokens');

    my $name = _get_name($ctx, $args);

    if( $name =~ s/ \[ ( \/? MT [^\]]+ ) \] /<$1>/gx ) {
        my $tok = $builder->compile($ctx, $name);
        $name = $builder->build($ctx, $tok) ||
            return $ctx->error($builder->errstr);
    }

    my $glue = $args->{glue} || '[\s,]+';
    my @names = split /$glue/, $name;

    my $out = '';
    for my $name (@names) {
        $ctx->stash('HelloWorldGreeted' => $name);
        $out .= $builder->build($ctx, $tokens) ||
            $ctx->error($builder->errstr);
    }

    return $out;
}

sub HelloWorldGreeted {
    my($ctx, $args) = @_;
    my $out = $ctx->stash('HelloWorldGreeted') 
           || $ctx->error('MTHelloWorldGreeted must be used in a '.
                          'MTHelloWorldContainer element.');
    return $out;
}

sub HelloWorldIfNameProvided {
    my($ctx, $args) = @_;
    my $out = $ctx->stash('HelloWorldGreeted');
    return $out && $out ne 'world';
}

sub to_uppercase {
    my($text, $value, $ctx) = @_;
    return uc $text;
}

sub _get_name {
    my($ctx, $args) = @_;
    my $e = $ctx->stash('entry');

    return  $args and defined $args->{name}      ?  $args->{name}
        :   $e && $e->author && $e->author->name ?  $e->author->name
        :                                           'world';
    
}

__END__

=head1 NAME

MT::Plugin::HelloWorld - Hacking Movable Type, Chapter Ten.

=head1 DESCRIPTION

This module is a simple example illustrating plugin basics, from the
the book, "Hacking Movable Type" and with the MT PluginManager
requirements - both linked below in the L</SEE ALSO> section.

The code is transcribed from "Hacking Movable Type" by Allen, Choate,
Hammersley, Haughey and Raynes, Chapter 10: "Writing Plugins."

The distribution of this plugin contains xml files that are required
by PluginManager, to allow automated updating.  Currently, the paths
specified in these files do not reference physical locations.

=head1 METHODS

=over 4

=item * HelloWorld

=item * HelloWorldContainer

=item * HelloWorldGreeted

=item * HelloWorldIfNameProvided

=item * to_uppercase

=back

=head1 EXAMPLES

    ### To all of you

        <$MTHelloWorld$>

    ### Dirified

        <$MTHelloWorld dirify="1"$>


    ### Showing excitement with a global attribute!

        <$MTHelloWorld to_uppercase="1"$>

    ### Hi Morty!

        <$MTHelloWorld name="Mortimer"$>

    ### Containers

    <MTHelloWorldContainer name="Byrne, Anil, Byron, Jay, world">
        Hello <$MTHelloWorldGreeted$>!
    </MTHelloWorldContainer>

    ### Containers with a conditional

    <MTHelloWorldContainer name="Byrne, Anil, Byron, Jay, world">
      <MTHelloWorldIfNameProvided>
        Hello <$MTHelloWorldGreeted$>! Nice to see you!
      <MTElse>
        Oh, it's you again, world.  Hi.
      </MTElse>
      </MTHelloWorldIfNameProvided>
    </MTHelloWorldContainer>

    ### In an entries loop

    <MTEntries>
        <$MTHelloWorld$>  Thanks for writing this entry.
    </MTEntries>

    ### Container inside of entry without tag

    <MTEntries>
    <MTHelloWorldContainer>
        Hello <$MTHelloWorldGreeted$>!
    </MTHelloWorldContainer>
    </MTEntries>

    ### Container inside of entry with tag as name variable

    <MTEntries>
    <MTHelloWorldContainer name="[MTEntryTags glue=','][MTTagName][/MTEntryTags]">
        This entry is tagged: <$MTHelloWorldGreeted$>
    </MTHelloWorldContainer>
    </MTEntries>

=head1 TO DO

XML files do not reference physical locations.

=head1 SEE ALSO

=head2 Hacking Movable Type

L<http://hackingmt.com/>

L<http://bradchoate.com/weblog/2005/08/01/hacking-movable-type>

=head2 PluginManager

The code: L<http://code.sixapart.com/svn/mtplugins/trunk/PluginManager/>.

The documentation: L<http://bradchoate.com/weblog/2005/08/01/hacking-movable-type>.

=head1 AUTHORS

=over 4

=item Brad Choate E<lt>brad@sixapart.comE<gt>

=item Jay Allen E<lt>jay@jayallen.orgE<gt>

=back

=cut