=head1 NAME

Template::Parser::RemoteInclude - call remote template-server inside your template

=head1 DESCRIPTION

You can write your own html aggregator for block build pages. 
However, this module allows you to make remote calls directly from the template. 
This is very useful when your project have a template server.

This module allows you to make any http-requests from template.

Depends on L<Template::Parser> and L<AnyEvent::Curl::Multi>. 

L<Curl::Multi> faster than L<LWP>. L<AnyEvent::Curl::Multi> much faster than L<LWP> ;)

Use and enjoy!

=head1 NOTE

=over 4

=item *

Directive C<RINCLUDE> like C<PROCESS>, but call remote uri.

=item *

Parser does not know anything about L<Template::Stash>, but knows about the variables passed in C<Template::process>.

=item *

Content of the response can be as a simple html or a new template

=item *

Contents of the response is recursively scanned for directives C<RINCLUDE> and makes additional request if necessary

=item *

The best option when your template-server is located on the localhost

=back

=head1 SYNOPSIS

create C<Template> object with C<Template::Parser::RemoteInclude> as parser.

    use Template;
    use Template::Parser::RemoteInclude;
    
    my $tt = Template->new(
         INCLUDE_PATH => '....',
         ....,
         PARSER       => Template::Parser::RemoteInclude->new(
             'Template::Parser' => {
                 ....,
             },
             'AnyEvent::Curl::Multi' => {
                max_concurrency => 10,
                ....,
             }
         )
    );

simple example include content C<http://ya.ru/> (with GET as http method)

    # example 1
    my $tmpl = "[% RINCLUDE GET 'http://ya.ru/' %]";
    $tt->process(\$tmpl,{});
    
    # example 2 - use variables passed in Template::process
    my $tmpl = "[% RINCLUDE GET ya_url %]";
    $tt->process(\$tmpl,{ya_url => 'http://ya.ru/'});
    
    # example 3 - set headers
    my $tmpl = "[% RINCLUDE GET ya_url ['header1' => 'value1','header2' => 'value2'] %]";
    $tt->process(\$tmpl,{ya_url => 'http://ya.ru/'});
    
    # example 4 - set headers
    my $tmpl = "[% RINCLUDE GET ya_url  headers %]";
    $tt->process(\$tmpl,{ya_url => 'http://ya.ru/', headers => ['header1' => 'value1','header2' => 'value2']});
    
    # example 5 - use HTTP::Request (with POST as http method) passed in Template::process
    my $tmpl = "[% RINCLUDE http_req_1 %]";
    $tt->process(
        \$tmpl,
        {
            http_req_1 => HTTP::Request->new(
                                                POST => 'http://ya.ru/', 
                                                ['header1' => 'value1','header2' => 'value2'], 
                                                $content
                                             )
        }
    );

example include remote template
    
    # http://example.com/get/template/hello_world => 
    # '<b>Hello, [% name %]!</b><br>[% name = "Boris" %][% RINCLUDE  "http://example.com/.../another" %]'
    # and
    # http://example.com/.../another => 
    # '<b>And goodbye, [% name %]!</b>'
    
    # example
    my $tmpl = "[% RINCLUDE GET 'http://example.com/get/template/hello_world' %]";
    $tt->process(\$tmpl,{name => 'User'});
    
    # returned
    <b>Hello, User!</b><br><b>And goodbye, Boris!</b>

more power example
    
    use Template;
    use Template::Parser::RemoteInclude;
    
    my $tt = Template->new(
         INCLUDE_PATH => '....',
         ....,
         PARSER       => Template::Parser::RemoteInclude->new(
             'Template::Parser' => {
                 ....,
             },
             'AnyEvent::Curl::Multi' => {
                max_concurrency => 10,
                ....,
             }
         ),
         WRAPPER => 'dummy.tt2'
    );    
    
    # where 'dummy.tt2'
    #    [% IF CSS %]
    #        [% FOREACH c = CSS %]
    #            css = [% c %]
    #        [% END %]
    #    [% END %]
    #    ====
    #    [% content %]
    #    ====
    
    # http://example.com/get/template/hello_world => 
    # "[% CSS.push('http://example.com/file.css') %]\nHello, [% name %]!\n"
    
    my $tmpl = "[% SET CSS = [] %][% RINCLUDE GET 'http://example.com/get/template/hello_world' %]";
    $tt->process(\$tmpl,{name => 'User'});
    
    # output:
    #    css = http://example.com/file.css
    #
    #    ====
    #        
    #    Hello, User!
    #        
    #    ====

=head1 METHODS

=head2 new('Template::Parser' => %param1, 'AnyEvent::Curl::Multi' => %param2)

Simple constructor

=head1 SEE ALSO

L<AnyEvent::Curl::Multi>, L<Template>

=head1 AUTHOR

mr.Rico <catamoose at yandex.ru>

=cut
