view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

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>

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


Remote RSS Feeds
----------------

Pages may use snippets of RSS feeds, limiting them to the given
number of entries.  For example:

    title: About my site
    feed: rss(4, http://blog.steve.org.uk/index.rss )
    ----
    <p>This page is about my site, here are my recent blog posts:</p>
    <ul>
    <!-- tmpl_loop name='feed' -->
        <li><a href="<!-- tmpl_var name='link' -->"><!-- tmpl_var name='title' --></a></li>
    <!-- /tmpl_loop -->
    </ul>


Redis Lookups
-------------

If you have a redis-server running upon the local system you may
configure page-variables to retrieve their values via lookups against it.

For example:

    title: Site Statistics
    count: redis_get( "global_count" )
    ----
    <p>There are <!-- tmpL-var name='count' --> entries.</p>


Installation
------------

Templer is developed in a public fashion, here on github, but stable releases
are also uploaded to CPAN:

* [App::Templer](http://search.cpan.org/dist/App-Templer/)

Installation should be as simple as any other CPAN-based module:

    $ git clone https://github.com/skx/templer.git
    $ cd templer
    $ perl Makefile.PL
    $ make test
    $ sudo make install

(If you ever wish to remove the software you may run `sudo make uninstall`.)

The code makes use of a reasonably large number of modules for its
implementation, and you can see a brief overview of [the logical structure](#object-hierarchy) later.)

If you want to get a standalone `templer` executable which includes all those `Templer` modules, you can use the `standalone` target of the generated `Makefile`:

    $ make standalone

This will produce a script called `templer` in the base directory so that you should be able to use it alone without copying these used modules anywhere in perl library directories.

The dependencies are minimal, to ease installation:

* Perl
* The [Module::Pluggable](http://search.cpan.org/perldoc?Module%3A%3APluggable) module for loading plugins.
* The [HTML::Template](http://search.cpan.org/perldoc?HTML%3A%3ATemplate) module.
    *  This may be installed, on a Debian system, with `apt-get install libhtml-template-perl`.
* The following are optional modules:
    * The [Image::Size](http://search.cpan.org/perldoc?Image%3A%3ASize) module is used if available whenever you create `file_glob`-using loops of image files.
        * This will set the attributes `width` and `height` any images added via `file_glob`.
    * The [Text::Markdown](http://search.cpan.org/perldoc?Text%3A%3AMarkdown) module is required if you wish to write your page bodies in Markdown.
        *  This may be installed, on a Debian system, with `apt-get install libtext-markdown-perl`.
    * The [Text::Textile](http://search.cpan.org/perldoc?Text%3A%3ATextile) module is required if you wish to write your page bodies in Textile.
        *  This may be installed, on a Debian system, with `apt-get install libtext-textile-perl`.
    * The [Text::Template](http://search.cpan.org/perldoc?Text%3A%3ATemplate) module is required if you wish to include dynamic perl in your input pages.
        *  This may be installed, on a Debian system, with `apt-get install libtext-template-perl`.
    * The [Redis](http://search.cpan.org/perldoc?Redis) module is required if you wish to use the Redis plugin.
        *  This may be installed, on a Debian system, with `apt-get install libredis-perl`.
    * The [XML::Feed](http://search.cpan.org/perldoc?XML%3A%3AFeed) module is required if you wish to use the RSS plugin.
        *  This may be installed, on a Debian system, with `apt-get install libxml-feed-perl`.

If you prefer you can install Debian binary packages from my personal repository:

* [templer repository for Debian GNU/Linux](http://packages.steve.org.uk/templer/)


Creating a new site
-------------------

There is a supplied script `templer-generate` which will create a new site-structure
if you give in the name of a directory to create & write to:

    ~$ templer-generate my-site
    ~$ tree my-site/
    my-site/
    ├── include
    ├── input
    │   ├── about.wgn
    │   ├── index.wgn
    │   └── robots.txt
    ├── layouts
    │   └── default.layout
    ├── output
    └── templer.cfg

If you prefer you may go through the process manually creating a directory,
adding the [`templer.cfg`](https://raw.github.com/skx/templer/master/templer.cfg.sample)
to it, and then creating the input tree and layout directory.

There are several [examples](examples/) provided with the distribution to illustrate the
software.  These example sites are built automatically every evening and
uploaded online - so you may easily compare the input and the generated
output:

* [simple example source](https://github.com/skx/templer/tree/master/examples/simple)
    * The online [generated output](http://www.steve.org.uk/Software/templer/examples/simple/output/).
* [complex example source](https://github.com/skx/templer/tree/master/examples/complex)
    * The online [generated output](http://www.steve.org.uk/Software/templer/examples/complex/output/).
    * The generated "complex" example is designed to be a standalone introduction to templer.


Rebuilding a site
-----------------

If you're beneath the directory containing your `templer.cfg` file simply
run `templer` with no arguments.  You may optionally add flags to control
what happens:

* `templer --verbose`
    * To see more details of what is happening.
* `templer --force`
    * To force a rebuild of the site.
* `templer --define foo=bar`
    * Define the variable `foo` for use in your templates.  This will over-ride any setting of foo in the configuration file you've loaded.

In the general case `templer` should rebuild only the files which are needed
to be built.  A page will be rebuilt if:

* The page source is edited.
* The layout the page uses is edited.
* Any include-file the page includes is edited.
    * This applies to those includes read via [read_file](#file-inclusion) rather than via `HTML::Template` includes

> Previously it was required that you run `templer` from the top-level of your site, this has now changed.  `templer` will walk upwards from the current working directory and attempt to find the site-root by itself.


Object Hierarchy
----------------

Although `templer` is distributed and used as a single script it is written
using a series of objects.  Bundling into a single binary allows for easier
distribution, installation and usage.

In brief the control flow goes like this:

* `templer` runs, parses the command line, etc.
* A `Templer::Global` object is created to read the `templer.cfg` file, or the file passed via `--config=foo`.
* The options from the command-line and the config file are merged.
* From this point onwards `Templer::Global` is ignored.
* A `Templer::Site` object is created, using the merged config values.
* A `Templer::Timer` object is created to record the build-time.
* The build process is contained in `Templer::Site::build()`:
    * A `Templer::Plugin::Factory` object is created to load plugins.
    * A `Templer::Site::Page` object is created for each appropriate input.
    * Each page is output.
    * The plugins are unloaded.
* The assets are copied via `Templer::Site::copyAssets()`.
* The output directory is cleaned via `Templer::Site::sync()`.
* The build-time/build-count is reported and the process is complete.

Each of the modules has a simple test-case associated with it.  To test functionality, especially after making changes, please run the test-suite: