# LIXUZ content management system
# Copyright (C) Utrop A/S Portu media & Communications 2012
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as
# published by the Free Software Foundation, either version 3 of the
# License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

=head1 LIXUZ TEMPLATE MANUAL

This is the Lixuz template manual for media templates.

This file describes version B<3> of the Lixuz template API.

B<Note>: the text in this file assumes you have already read the general
template introduction found in doc/templates.pod of the Lixuz source tree.

=head1 INTRODUCTION TO MEDIA TEMPLATES

A media template is what Lixuz uses to render inline images. It's special
because Lixuz doesn't use them to render any page, and they can't be called
by other templates. The media templates will be called while Lixuz is
preparing an article string for display. It's used so that images that are
added inline into ie. the article body can still be formatted. The templates
are called once for each image present in the string, and can be cached for
an arbitrary amount of time. As such you shouldn't rely upon getting called
several times, it is entirely possible that the template is only called once
for an article in a period of several weeks (all depending on cache settings).

Media templates are also limited in the amount of data that they have available,
and they are unable to poll the Lixuz template engine for additional data, like
ie. web templates can. That being said, they are still full HTML::Mason templates.

=head2 Processing overview for media templates

=over

=item Step 1

Lixuz retrieves an image from a string, by parsing it as a HTML DOM-tree.
It then fetches the lz_file object from the database. Then it calculates
the size of the file.

=item Step 2

It hands control over to the template, with the data defined in the B<AVAILABLE
DATA> section.

=item Step 3

The rendered template gets parsed as a HTML DOM-tree. Lixuz looks for an <img>
element that has the class 'lzImagePlaceholder'. It then merges the attributes
of the <img> tag in the original string, with the attributes of the <img> tag
from the template, overwriting settings in the template if needed (style=""
tags are handled separately, and Lixuz attempts to merge those directly, so
that styling from the template isn't lost).

It will then remove lzImagePlaceholder from the class attribute.

=item Step 4

It returns to step 1 if there are more images, otherwise the generated
string is returned to caller.

=back

=head1 AVAILABLE DATA

Lixuz will provide you with some very specific data that you can use 
while rendering it. Each of the variables are provided as Mason arguments,
and you can retrieve them by including them in your <%args> block.

=over

=item $image

Never undef. This is the LIXUZDB::LzFile object that is being rendered.
Keep in mind that you don't have to fetch any url for this image, as Lixuz
will insert that into the <img> tag with the lzImagePlaceholder class
after the template has rendered.

=item $type

This is used to be able to support rendering of ie. videos in the future.
For now, it will always be the string 'image'.

=item $height

Never undef. The height of the image (after resizing).

=item $width

Never undef. The width of the image (after resizing).

=item $caption

Can be undef if the image has no caption. This is the caption string for the
image.

=item $float

Can be undef. The CSS float value for the image, you can use this to align
a container block.

=back

=head1 INFOBLOCK DATA

The Lixuz infoblock can contain various pieces of information. The entries that
are required to be present are: NAME LICENSE VERSION
TYPE APIVERSION and UNIQUEID.

Here follows a list of all possible infoblock entries, and their permitted
values and syntax. Please note that unlike web templates, you can not
use INCLUDES or NEEDSINFO in media templates.

=over

=item B<VERSION>

This option should contain the version number of your template. This is
mostly present to let you track versions yourself, but might also be used
by Lixuz in the future. It accepts any string and is required.

=item B<NAME>

This option should contain the human-readable name of the template. This
is the string that will be displayed within the Lixuz interface. It accepts
any string and is required.

=item B<LICENSE>

This option should contain the license of your template. Like VERSION
this is mostly present to let you track which license a template has yourself
and to let you find out if you can redistribute that nice template you have.
It accepts any string and is required.

=item B<APIVERSION>

This option must contain the Lixuz template API version the template is written
for, as of this document that version is 1. This will make sure that Lixuz does
not accept templates for newer versions than the one installed, and might also
allow it to activate a compatibility mode in the future for templates that
are using an old api version. It accepts a single integer and is required.

=item B<TYPE>

This option determines which type of template it is, and thus also what Lixuz
will use it for. For media templates it should be set to "media".

=item B<MEDIASETTINGS>

This option lets you change some parameters of how Lixuz will treat the images
that will be used. It takes a set of parameters surrounded by square-brackets
([ ]).

The settings it permits you to set are (all optional):

=over

=item maxWidth, maxHeight

These specify the maximum height and width of an image that will be rendered
with this template. You will never get an image that has dimensions that are
larger than this. This is equivalent to the parameters that can be supplied to
the LIXUZ::HelperModules::HTMLRenderer object within Lixuz.

=item noFloat

This can be set to true to force Lixuz not to honor or add float styles to
images.

=back

=back

=head1 EXAMPLES

=head2 Bare-bones

The simplest template possible could be written like this:

    <img class="lzImagePlaceholder" />
    <%once>
    # BEGIN LIXUZ_INFOBLOCK
    # VERSION=0.1
    # NAME=Lixuz media renderer
    # LICENSE=Proprietary
    # APIVERSION=1
    # TYPE=media
    # UNIQUEID=org.example.media
    # MEDIASETTINGS=maxWidth=400,maxHeight=400,noFloat=true
    # END LIXUZ_INFOBLOCK
    </%once>

Hopefully this should make it a bit clearer. You can do anything you want with
that markup, as long as you have an img tag with the lzImagePlaceholder class.

=head2 Fleshed-out

=head3 Template code

    <div class="inlineImageContainer" style="float:<% $float %>; width:<%$width%>px">
        <div>
            <img class="lzImagePlaceholder" />
            <div style="clear:both;"></div>
        </div>
    %if($caption) {
        <div class="imageCaption"><% $caption |n %></div>
    %}
    %if(my $name = $image->getFieldContents($c,7)) {
        <div>Photographer: <% $name |n %></div>
    %}
    </div>
    <%args>
    $image
    $width
    $height
    $caption
    $float => 'left'
    </%args>
    <%once>
    # BEGIN LIXUZ_INFOBLOCK
    # VERSION=0.1
    # NAME=Lixuz media renderer
    # LICENSE=Proprietary
    # APIVERSION=1
    # TYPE=media
    # UNIQUEID=org.example.media
    # END LIXUZ_INFOBLOCK

=head3 Rendered code

    <div class="inlineImageContainer" style="float:right; width:250px">
        <div>
            <img alt="" class="" src="http://example.org/files/get/9xuL?width=250" style="width:250px;float:right;height:166px;border:1px solid black;" />
            <div style="clear:both;"></div>
        </div>
        <div class="imageCaption">Example caption</div>
        <div>Photographer: Pixelensphotography.com</div>
    </div>
