Sanko Robinson > Solution > Solution

Download:
Solution-v0.9.1.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: v0.9.1   Source  

NAME ^

Solution - A Simple, Stateless Template System

Synopsis ^

    use Solution;
    my $template = Solution::Template->new();
    $template->parse(    # See Solution::Tag for more examples
          '{% for x in (1..3) reversed %}{{ x }}, {% endfor %}{{ some.text }}'
    );
    print $template->render({some => {text => 'Contact!'}}); # 3, 2, 1, Contact!

Description ^

Solution is a template engine based on Liquid. The Liquid template engine was crafted for very specific requirements:

Getting Started ^

It's very simple to get started with Solution. Just as in Liquid, templates are built and used in two steps: Parse and Render.

    my $sol = Solution::Template->new();  # Create a Solution::Template object
    $sol->parse('Hi, {{name}}!');         # Parse and compile the template
    $sol->render({name => 'Sanko'});      # Render the output => "Hi, Sanko!"

    # Or if you're in a hurry...
    Solution::Template->parse('Hi, {{name}}!')->render({name => 'Sanko'});

The parse step creates a fully compiled template which can be re-used as often as you like. You can store it in memory or in a cache for faster rendering later.

All parameters you want Solution to work with have to be passed as parameters to the render method. Solution is a closed ecosystem; it does not know about your local, instance, global, or environment variables.

For an expanded overview of the Liquid/Solution syntax, please see Solution::Tag and read Liquid for Designers.

Extending Solution ^

Extending the Solution template engine for your needs is almost too simple. Keep reading.

Custom Filters

Filters are simple subs called when needed. They are not passed any state data by design and must return the modified content.

TODO: I need to write Solution::Filter which will be POD with all sorts of info in it. Yeah.

Solution->register_filter( ... )

This registers a package which Solution will assume contains one or more filters.

    # Register a package as a filter
    Solution->register_filter( 'SolutionX::Filter::Amalgamut' );

    # Or simply say...
    Solution->register_filter( );
    # ...and Solution will assume the filters are in the calling package

Solution->filters( )

Returns a list containing all the tags currently loaded for informational purposes.

Custom Tags

See the section entitled Extending Solution with Custom Tags in Solution::Tag for more information.

To assist with custom tag creation, Solution provides several basic tag types for subclassing and exposes the following methods:

Solution->register_tag( ... )

This registers a package which must contain (directly or through inheritance) both a parse and render method.

    # Register a new tag which Solution will look for in the given package
    Solution->register_tag( 'newtag', 'SolutionX::Tag::You're::It' );

    # Or simply say...
    Solution->register_tag( 'newtag' );
    # ...and Solution will assume the new tag is in the calling package

Pre-existing tags are replaced when new tags are registered with the same name. You may want to do this to override some functionality.

Solution->tags( )

Returns a hashref containing all the tags currently loaded for informational purposes.

Why should I use Solution? ^

Why shouldn't I use Solution? ^

'Solution to what?' or 'Ugh! Why a new Top Level Namespace?' ^

I really don't have a good reason for claiming a new top level namespace and I promise to put myself in timeout as punishment.

As I understand it, the original project's name, Liquid, is a reference to the classical states of matter (the engine itself being stateless). I settled on Solution because it's Liquid but... with... bits of other stuff floating in it. (Pretend you majored in chemistry instead of mathematics or computer science.) Liquid tempates will always be work with Solution but (due to Solution's expanded syntax) Solution templates may not be compatible with Liquid.

This 'solution' is not the answer to all your problems and obviously not the only solution for your templating troubles. It's simply a solution.

Author ^

Sanko Robinson <sanko@cpan.org> - http://sankorobinson.com/

CPAN ID: SANKO

The original Liquid template system was developed by jadedPixel and Tobias Lütke.

License and Legal ^

Copyright (C) 2009,2010 by Sanko Robinson <sanko@cpan.org>

This program is free software; you can redistribute it and/or modify it under the terms of The Artistic License 2.0. See the LICENSE file included with this distribution or notes on the Artistic License 2.0 for clarification.

When separated from the distribution, all original POD documentation is covered by the Creative Commons Attribution-Share Alike 3.0 License. See the clarification of the CCA-SA3.0.

syntax highlighting: