NAME
    Template::Liquid - A Simple, Stateless Template System

Synopsis
        use Template::Liquid;
        my $template = Template::Liquid->new();
        $template->parse(    # See Template::Liquid::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
    Template::Liquid is a template engine based on Liquid. The Liquid
    template engine was crafted for very specific requirements:

    *   It has to have simple markup and beautiful results. Template engines
        which don't produce good looking results are no fun to use.

    *   It needs to be non-evaling and secure. Liquid templates are made so
        that users can edit them. You don't want to run code on your server
        which your users wrote.

    *   It has to be stateless. The compile and render steps have to be
        separate, so that the expensive parsing and compiling can be done
        once; later on, you can just render it by passing in a hash with
        local variables and objects.

    *   It needs to be able to style emails as well as HTML.

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 = Template::Liquid->new();    # Create a Template::Liquid 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...
        Template::Liquid->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 Template::Liquid to work with have to be passed
    as parameters to the "render" method. Template::Liquid 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
    Template::Liquid::Tag and read Liquid for Designers
    <http://wiki.github.com/tobi/liquid/liquid-for-designers>.

Extending Template::Liquid
    Extending the Template::Liquid 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.

   "Template::Liquid->register_filter( ... )"
    This registers a package which Template::Liquid will assume contains one
    or more filters.

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

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

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

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

   "Template::Liquid->register_tag( ... )"
    This registers a package which must contain (directly or through
    inheritance) both a "parse" and "render" method.

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

        # Or simply say...
        Template::Liquid->register_tag( 'newtag' );
        # ...and Template::Liquid 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.

    For an example of a custom tag, see Template::Solution::Tag::Include.

Why should I use Template::Liquid?
    *   You want to allow your users to edit the appearance of your
        application, but don't want them to run insecure code on your
        server.

    *   You want to render templates directly from the database.

    *   You like Smarty-style template engines.

    *   You need a template engine which does HTML just as well as email.

    *   You don't like the markup language of your current template engine.

    *   You wasted three days reinventing this wheel when you could have
        been doing something productive like volunteering or catching up on
        past seasons of *Doctor Who*.

Why shouldn't I use Template::Liquid?
    *   You've found or written a template engine which fills your needs
        better than Liquid or Template::Liquid ever could.

    *   You are uncomfortable with text that you didn't copy and paste
        yourself. Everyone knows computers cannot be trusted.

Template::LiquidX or Template::Solution?
    I'd really rather use Template::Solution::{Package} for extentions but
    who cares? Namespaces are kinda useless if you're the only person using
    the code.

    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 <http://en.wikipedia.org/wiki/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 Template::Liquid but (due to
    Template::Solutions's expanded syntax) Template::Solution templates *may
    not* be compatible with Liquid or Template::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
    <http://jadedpixel.com/> and Tobias Ltke <http://blog.leetsoft.com/>.

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
    <http://www.perlfoundation.org/artistic_license_2_0>. See the LICENSE
    file included with this distribution or notes on the Artistic License
    2.0 <http://www.perlfoundation.org/artistic_2_0_notes> for
    clarification.

    When separated from the distribution, all original POD documentation is
    covered by the Creative Commons Attribution-Share Alike 3.0 License
    <http://creativecommons.org/licenses/by-sa/3.0/us/legalcode>. See the
    clarification of the CCA-SA3.0
    <http://creativecommons.org/licenses/by-sa/3.0/us/>.

