Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cafe01/template-plift


https://github.com/cafe01/template-plift

Last synced: about 2 months ago
JSON representation

Awesome Lists containing this project

README

        

[![Build Status](https://travis-ci.org/cafe01/template-plift.svg?branch=master)](https://travis-ci.org/cafe01/template-plift) [![Coverage Status](https://img.shields.io/coveralls/cafe01/template-plift/master.svg?style=flat)](https://coveralls.io/r/cafe01/template-plift?branch=master)
# NAME

Plift - HTML Template Engine + Custom HTML Elements

# SYNOPSIS

use Plift;

my $plift = Plift->new(
path => \@paths, # default ['.']
plugins => [qw/ Script Blog Gallery GoogleMap /], # plugins not included
);

my $tpl = $plift->template("index");

# set render directives
$tpl->at({
'#name' => 'fullname',
'#contact' => [
'.phone' => 'contact.phone',
'.email' => 'contact.email'
]
});

# render render with data
my $document = $tpl->render({

fullname => 'Carlos Fernando Avila Gratz',
contact => {
phone => '+55 27 1234-5678',
email => '[email protected]'
}
});

# print
print $document->as_html;

# DESCRIPTION

Plift is a HTML template engine which enforces strict separation of business logic
from the view. It is designer friendly, safe, extensible and fast enough to
be used as a web request renderer. This engine tries to follow the principles
described in the paper _Enforcing Strict Model-View Separation in Template Engines_
by Terence Parr of University of San Francisco. The goal is to provide suficient
power without providing constructs that allow separation violations.

# MANUAL

This document is the reference for the Plift class. The manual pages (not yet
complete) are:

- [Plift::Manual::Tutorial](https://metacpan.org/pod/Plift::Manual::Tutorial)

Step-by-step intruduction to Plift. "Hello World" style.

- [Plift::Manual::DesignerFriendly](https://metacpan.org/pod/Plift::Manual::DesignerFriendly)

Pure HTML5 template files makes everything easier to write and better to maintain.
Designers can use their WYSIWYG editor, backend developers can unit test their
element renderers.

- [Plift::Manual::Inception](https://metacpan.org/pod/Plift::Manual::Inception)

Talks about the web framework that inspired Plift, and its 'View-First'
approach to web request handling. (As opposed to the widespread 'Controller-First').

- [Plift::Manual::CustomHandler](https://metacpan.org/pod/Plift::Manual::CustomHandler)

Explains how Plift is just an engine for reading/parsing HTML files, and
dispaching subroutine handlers bound to XPath expressions. You will learn how
to write your custom handlers using the same dispaching loop as the builtin
handlers.

# METHODS

## add\_handler

- Arguments: \\%parameters

Binds a handler to one or more html tags, attributes, or xpath expression.
Valid parameters are:

- tag

Scalar or arrayref of HTML tags bound to this handler.

- attribute

Scalar or arrayref of HTML attributes bound to this handler.

- xpath

XPath expression matching the nodes bound this handler.

See [Plift::Manual::CustomHandler](https://metacpan.org/pod/Plift::Manual::CustomHandler).

## template

$context = $plift->template($template_name, \%options)

Creates a new [Plift::Context](https://metacpan.org/pod/Plift::Context) instance, which will load, process and render
template `$template_name`. See ["at" in Plift::Context](https://metacpan.org/pod/Plift::Context#at), ["set" in Plift::Context](https://metacpan.org/pod/Plift::Context#set) and
["render" in Plift::Context](https://metacpan.org/pod/Plift::Context#render).

## process

$document = $plift->process($template_name, \%data, \@directives)

A shortcut method.
A new context is created via ["template"](#template), rendering directives are set via
["at" in Plift::Context](https://metacpan.org/pod/Plift::Context#at) and finally the template is rendered via ["render" in Plift::Context](https://metacpan.org/pod/Plift::Context#render).
Returns a [XML::LibXML::jQuery](https://metacpan.org/pod/XML::LibXML::jQuery) object representing the final processed document.

my %data = (
fullname => 'John Doe',
contact => {
phone => 123,
email => 'foo@example'
}
);

my @directives =
'#name' => 'fullname',
'#name@title' => 'fullname',
'#contact' => {
'contact' => [
'.phone' => 'phone',
'.email' => 'email',
]
);

my $document = $plift->process('index', \%data, \@directives);

print $document->as_html;

## render

$html = $plift->render($template_name, \%data, \@directives)

A shortcut for `$plift->process()->as_html`.

## load\_components

$plift = $plift->load_components(@components)

Loads one or more Plift components. For each component, we build a class name
by prepending `Plift::` to the component name, then load the class, instantiate
a new object and call `$component->register($self)`.

See [Plift::Manual::CustomHandler](https://metacpan.org/pod/Plift::Manual::CustomHandler).

# SIMILAR PROJECTS

This is a list of modules (that I know of) that pursue similar goals:

- [HTML::Template](https://metacpan.org/pod/HTML::Template)

Probably one of the first to use (almost) valid html files as templates, and
encourage less business logic to be embedded in the templates.

- [Template::Pure](https://metacpan.org/pod/Template::Pure)

Perl implementation of Pure.js. This module inspired Plift's render directives.

- [Template::Semantic](https://metacpan.org/pod/Template::Semantic)

Similar to Template::Pure, but the render directives points to the actual data
values, instead of datapoints. Which IMHO makes the work harder.

- [Template::Flute](https://metacpan.org/pod/Template::Flute)

Uses a XML specification format for the rendering directives. Has lots of other
features.

# LICENSE

Copyright (C) Carlos Fernando Avila Gratz.

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

# AUTHOR

Carlos Fernando Avila Gratz