Alan Ferrency > Text-MicroMason-2.13 > Text::MicroMason::HTMLMason

Download:
Text-MicroMason-2.13.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  1
View/Report Bugs
Source  

NAME ^

Text::MicroMason::HTMLMason - Simple Compiler for Mason-style Templating

SYNOPSIS ^

Create a MicroMason object to interpret the templates:

  use Text::MicroMason;
  my $mason = Text::MicroMason->new();

Use the standard compile and execute methods to parse and evalute templates:

  print $mason->compile( text=>$template )->( @%args );
  print $mason->execute( text=>$template, @args );

Mason syntax provides several ways to mix Perl into a text template:

  <%args>
    $name
  </%args>

  % if ( $name eq 'Dave' ) {
    I'm sorry <% $name %>, I'm afraid I can't do that right now.
  % } else {
    <%perl>
      my $hour = (localtime)[2];
      my $daypart = ( $hour > 11 ) ? 'afternoon' : 'morning'; 
    </%perl>
    Good <% $daypart %>, <% $name %>!
  % }

  <& "includes/standard_footer.msn" &>

  <%doc>
    Here's a private developr comment describing this template. 
  </%doc>

DESCRIPTION ^

The Text::MicroMason::HTMLMason class provides lexer and assembler methods that allow Text::MicroMason to handle most elements of HTML::Mason's template syntax.

Compatibility with HTML::Mason

HTML::Mason is a full-featured application server toolkit with many fatures, of which only the templating functionality is emulated.

The following sets of HTML::Mason features are supported by Text::MicroMason:

The following sets of HTML::Mason features are not supported by Text::MicroMason:

Contributed patches to add these features of HTML::Mason would be welcomed by the author. Possible implemenations are described in Text::MicroMason::ToDo.

Private Methods

The following internal methods are used to implement the syntax described below.

lex_token
  ( $type, $value ) = $mason->lex_token();

Supports HTML::Mason's markup syntax.

Attempts to parse a token from the template text stored in the global $_ and returns a token type and value. Returns an empty list if unable to parse further due to an error.

assembler_rules()

Returns a hash of text elements used for Perl subroutine assembly. Used by assemble().

Supports HTML::Mason's named blocks of Perl code and documentation: %once, %init, %cleanup, and %doc.

assemble_args

Called by assemble(), this method provides support for Mason's <%args> blocks.

TEMPLATE SYNTAX ^

Here's an example of Mason-style templating, taken from HTML::Mason:

    % my $noun = 'World';
    Hello <% $noun %>!
    How are ya?

Interpreting this template with Text::MicroMason produces the same output as it would in HTML::Mason:

    Hello World!
    How are ya?

Text::MicroMason::HTMLMason supports a syntax that is mostly a subset of that used by HTML::Mason.

Template Markup

The following types of markup are recognized in template pages:

Named Blocks

The following types of named blocks are supported:

The following types of named blocks are not supported by HTML::Mason, but are supported here as a side-effect of the way the lexer and assembler are implemented.

TEMPLATE CODING TECHNIQUES ^

Assembling Perl Source Code

When Text::MicroMason::Base assembles your lexed template into the equivalent Perl subroutine, all of the literal (non-Perl) pieces are converted to $_out->('text'); statements, and the interpolated expressions are converted to $_out->( do { expr } ); statements. Code from %perl blocks and % lines are included exactly as-is.

Your code is eval'd in the Text::MicroMason::Commands package. The use strict; pragma is enabled by default to simplify debugging.

Internal Sub-templates

You can create sub-templates within your template text by defining them as anonymous subroutines and then calling them repeatedly. For example, the following template will concatenate the results of the draw_item sub-template for each of three items:

    <h1>We've Got Items!</h1>
    
    % my $draw_item = sub {
      <p><b><% $_[0] %></b>:<br>
        <a href="/more?item=<% $_[0] %>">See more about <% $_[0] %>.</p>
    % };
    
    <%perl>
      foreach my $item ( qw( Foo Bar Baz ) ) {
        $draw_item->( $item );
      }
    </%perl>

Returning Text from Perl Blocks

To append to the result from within Perl code, call $_out->(text). (The $_out->() syntax is unavailable in older versions of Perl; use the equivalent &$_out() syntax instead.)

For example, the below template text will return '123456789' when it is evaluated:

    <%perl>
      foreach my $digit ( 1 .. 9 ) {
        $_out->( $digit )
      }
    </%perl>

You can also directly manipulate the value @OUT, which contains the accumulating result.

For example, the below template text will return an altered version of its message if a true value for 'minor' is passed as an argument when the template is executed:

    This is a funny joke.
    % if ( $ARGS{minor} ) { foreach ( @OUT ) { tr[a-z][n-za-m] } }

SEE ALSO ^

For a full-featured web application system using this template syntax, see HTML::Mason.

For an overview of this distribution, see Text::MicroMason.

This is a subclass intended for use with Text::MicroMason::Base.

For distribution, installation, support, copyright and license information, see Text::MicroMason::Docs::ReadMe.

syntax highlighting: