infosophie/vinyl

Templating Engine for PHP

Maintainers

Details

gitlab.com/infosophie/vinyl

Source

Issues

Installs: 3

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Forks: 0

v0.1.2 2022-10-01 21:22 UTC

MIT c104f3c5a2b06b7f4a1af5af84b8cd5e8c703f97

  • Christian Grauer <mail.woop@cgrauer.de>

This package is not auto-updated.

Last update: 2024-05-27 00:34:58 UTC

README

Infosophie::Vinyl is a php templete engine. It's focus is on instantly creating simple and php conform templates for use in your php project.

Installation

composer require infosophie/vinyl

or

"require": {
    "infosophie/vinyl": "main"
}

Usage

Including Vinyl

If you use composer, just "use" Infosophie\Vinyl\Engine

use Infosophie\Vinyl\Engine;

Without composer, first include_once the file vinyl/src/Engine.php:

include_once("vendor/infosophie/vinyl/src/Engine.php");
use Infosophie\Vinyl\Engine;

The path depends on where you store Infosophie::Vinyl.

Quick Start

Create a template file helloworld.tpl somewhere in your project path and enter the follwing content:

<h1>Hello World, I am <%name%></h1>

In your php script, create a new instance from Infosophie\Vinyl\Engine passing the path to the folder where your template is stored:

...
$vinyl = new Infosophie\Vinyl\Engine(['vinyl/templates']);

Mind the array: the path is passed to Engine as an array with just 1 element. This is necessary because you may pass multiple paths to search for templates (see below...).

To get your template rendered, call the render() function with your template name and all the data for the placeholders (<%...%>) in an array:

include_once("vendor/infosophie/vinyl/src/Engine.php");

use Infosophie\Vinyl\Engine;

$vinyl = new Infosophie\Vinyl\Engine(['vinyl/templates']);
echo $vinyl->render("helloworld", ['name' => 'Christian Grauer']);

This is what you should see in your browser (the source):

<h1>Hello World, I am Christian Grauer</h1>

Hint: Replace my name with yours to make it more personal ;-)

So this is how template engines work: They replace placeholders with data!

Features

These are the main features of Vinyl:

  • Placeholders can use data from:
    • elements in the array passed to render()
    • values of associative arrays in unlimited depth
    • functions from inside your project
  • PHP/HTML integration
    • you may use plain php code in the template, just wrap it with "<?php" and "?>" as you always do.
    • you also use plain html and it will remain untouched
  • Including and Wrapping Templates
    • include sub-templates that use the same data as the primary template
    • wrap the template with other templates (e.g. use generic header and footer for all templates)

Syntax

Vinyl's syntax is easy and smart:

  1. PHP: you may use plain php as if your template was just another include-file
  2. HTML: all html code will remain untouched. Design all static parts of your template as if it was just a html file
  3. Placeholders: The syntax of placeholders is simple: wrap the identifier with "<%" and "%>", that's it.
    • Array values are referenced in "object-style" using a dot between array-name and element key: <%myarray.key1.subkey%>
  4. Functions: there are some integrated functions (like include and wrap) and it's possible to add custom functions that call "real" functions in your php code. Both have the same syntax, it's like "<%functionname(parameter1|parameter2)%>".
    • Parameters are passed to the functions. For 'include' and 'wrap' there is only 1 parameter and it's the template's name
    • Multiple parameters (e.g. for custom functions) are separated with a pipe (|)
    • No quotation marks are needed: just write the content inside the parenthesis: <%myfunction(this is content|and this)%>

That's it. No need to learn a complete new language...

Customizing

Vinyl can be customized in various ways:

  • Filenames: the extension ".tpl" can be changed to whatever you like
  • Placeholders: the "<%" and "%>" tags for placeholders can also be changed to whatever you prefer (as long it is are appropriate to identify the placeholders...)
  • inject your own functions to Vinyl

Themes

Vinyl supports themes. You may pass as many template path's to Vinyl as you want. Templates are each searched one after another in all path's. This is how you may apply theming to your project with no effort.

Say you have templates for a default presentation and you have some customized templates for custom themes in your porject. Just pass both paths to Vinyl, first the theme-path, then the default-path:

...
$vinyl = new Infosophie\Vinyl\Engine(['themes/mytheme/templates', 'templates']);
...

For each template you call with render(), Vinyl will first search it in the first path (themes/mytheme/templates). If Vinyl can't find it there, it will search it in the second path (templates). This means, for a theme you don't have to create or copy every template, but just the ones that differ from your default templates.

Custom Functions

Custom functions are used in the templates the same way internal functions are. But custom functions have to be shared with Vinyl before templates can use it.

If you want to share a function with Vinyl, call the method "customFunction()" on your vinyl instance:

...
$vinyl = new Infosophie\Vinyl\Engine(['themes/mytheme/templates', 'templates']);
$vinyl->customFunction('link', 'getLink', $this);
echo $vinyl->render('mytemplate');
...

In this snippet, the function "getLink()" is passed to Vinyl under the name "link".

  • The first parameter is the function name that will be used in the templates.
  • The second parameter is the name of the function in your code, i.e. if templates call the function <%link()%>, your function "getLink()" will be called and whatever it returns will be the output of <%link()%>.
  • The third (optional) parameter is the object or the class of which the function is a method of, in the case above its the same object that calls vinyl, so we can use $this for it. The method you pass to vinyl has to be public. If you pass an object or class that is not the same as the calling class, you have to make sure that Vinyl has access to it! If you pass a class name instead of an object instance, you have to make sure that the method you use is static (can be called like Classname::method())!

If you call link() in your templates, you have to pass all the parameters that getLink() requires!

To make clear how custom functions work, let's have a look on a real example:

This be your projects code:


namespace Myproject;

use Infosophie\Vinyl\Engine;

class presentation {

    ...

    public function output() {
        $vinyl = new Engine('templates');   # create vinyl object, templates are in folder "templates"
        $vinyl->customFunction('link', 'getLink', $this); # add getLink() as a custom function
        $vinyl->render('linklist'); # render the template linklist.tpl
    }

    public function getLink($url) {
        return "<a href=\"" . $url . "\">" .$url . "</a>";
    }
}

This be your template "templates\linklist.tpl":

<h1>Linklist</h1>
<ul>
    <li><%link(http://www.infosophie.de)%></li>
    <li><%link(http://www.cgrauer.de)%></li>
    <li><%link(http://www.schachtelhalm.net)%></li>
</ul>

This is what vinyl->render() returns for output:

<h1>Linklist</h1>
<ul>
    <li><a href="http://www.infosophie.de">http://www.infosophie.de</a></li>
    <li><a href="http://www.cgrauer.de">http://www.cgrauer.de</a></li>
    <li><a href="http://www.schachtelhalm.net">http://www.schachtelhalm.net</a></li>
</ul>

customFunctions are shard with the Vinyl instance ($vinyl in example above) and will be avialable for all templates rendered using that instance! So you have to call customFunction() only once for each function and Vinyl instance.

Reference

Variables

<%label%>

Include

<%include(templatename)%>

Wrap

<%wrap(templatename)%>

Custom Functions

<%functionname(parameter1|parameter2|$variable1...)%>

Loop

<%loop(array):id=value%>
...content...
<%/%>

or

<%loop(array):value%>
...content...
<%/%>