view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

    ----
    <p>Hello, my name is <!-- tmpl_var name='name' -->.</p>

> **NOTE**: All variable-names are transformed to lower-case for consistency, which is why we refer to the variable `name` rather than the defined `Name`.

As well as simple "name: value" pairs there are also additional options implemented in [plugins](PLUGINS.md);

* A variable may refer to the contents of a given file.
    * Using `read_file`.
* A variable may refer to a list of filenames, matching a pattern.
    * Using `file_glob`.
* A variable may contain the output of running a command.
    * Using `run_command`.
* A variable may be based on the timestamp of the input page.
    * Using `timestamp`.
* A variable may contain the contents of a remote RSS feed.
    * Using `rss(count, URL)`.
* A variable may contain the result of a key-lookup from a Redis server.
    * Using `redis_get('foo')`.

In addition to declaring variables in a page-header you may also declare
__global__ variables in your `templer.cfg` file, or upon the command-line
via `--define foo=bar`.

Defining global variables is demonstrated in the sample [`templer.cfg`](https://raw.github.com/skx/templer/master/templer.cfg.sample) file.


File Globbing Variables
-----------------------

We've already seen simple variables declared by `key: value` in the page header,
in addition to this you may define a variable that refers to a number of files
by pattern.

Here is a simple example of creating a gallery which will include files matching
the pattern `img/*.jpg`:

    Title: My gallery
    Images: file_glob( "img/*.jpg" )
    ---
    <!-- tmpl_if name='images' -->
      <!-- tmpl_loop name='images' -->
       <p><img src="<!-- tmpl_var name='file' -->"
               height="<!-- tmpl_var name='height' -->"
               width="<!-- tmpl_var name='width' -->" /> </p>
      <!-- /tmpl_loop -->
    <!-- tmpl_else -->
      <p>No images were found.</p>
    <!-- /tmpl_if -->

> **TIP**:  If your images are numbered numerically you can ensure their correct order by doing this:

    Title:  This is my title
    images: file_glob( img/[0-9].jpg img/1[0-9].jpg )
    ----
    <p>My gallery is now included in ascending numerical order:</p>


This facility is implemented in the `Templer::Plugin::FileGlob` [plugin](PLUGINS.md).

The file glob is primarily designed for handling image-galleries, which is why it will set the `height` and `width` attributes if your glob matches `*.jpg`, `*.png`, etc.  However it can also be used for non-images.

If your glob matches files which are not images it will populate the member `content`, being the text-content of the matching files.  This allows you to include files easily.  For example:


    Title: This is my news-page
    news: file_glob( news-*.txt )
    ----
    <p>Here are the recent events:</p>
    <!-- tmpl_loop name='news' -->
    <p><!-- tmpl_var name='content' --></p>
    <!-- /tmpl_loop -->

This assumes you have files such as `news-20130912.txt`, etc, and will show the contents of each file in (glob)order.</p>

If matching files are templer input files then all templer variables are populated instead of the text-content of the matching files.

In all cases it will populate `dirname`, `basename` and `extension`, being parts of each matching files name.


File Inclusion
--------------

The [HTML::Template](http://search.cpan.org/perldoc?HTML%3A%3ATemplate) module supports file inclusion natively, via the following construct:

    <p>This is some text.</p>
    <!-- tmpl_include name='/etc/passwd' -->
    <p>That was my password file.</p>

In addition to this you may define a variable to contain the contents of a specified file.  For example:

    Title: This file has my passwords!
    Passwd: read_file( "/etc/passwd" )
    ----
    <p>Please see my passwords:</p>
    <pre><!-- tmpl_var name='passwd' -->
    </pre>

This facility is implemented in the `Templer::Plugin::FileContents` [plugin](PLUGINS.md).

Include files, whether included via the `read_file` method, or via the native HTML::Template faclity, are searched for in the same fashion:

* If the filename is fully-qualified, then the absolute path-name will be used.
* Otherwise the include-path will be searched.
* After the include-path has been searched the file will be looked for in the location relative to the input page location.

This allows you to place all your include-files in a single directory which is outside your web-root.

> **TIP**: The advantage of choosing to use `read_file` over the native HTML::Template support is that with the former the output page will be automatically rebuilt if you modify the include file.


Shell Command Execution
-----------------------

Pages may also define variables which receive the value of the output of shell commands.  This is done via definitions like this:


    Title: This file is dynamic
    Host: run_command( "hostname" )
    ----
    <p>This page was built upon <!-- tmpl_var name='host' -->.</p>