League Plates Renderer Add-on - BitFrame PHP Microframework

League Plates

The PHP League Plates template renderer for BitFrame microframework

{
    "require": {
		"designcise/bitframe-leagueplates": "^1.0.0"
	}
}

Install

Add the following as a dependency in your project's composer.json:

"designcise/bitframe-leagueplates": "^1.0.0"

Getting Started →

use \BitFrame\Application;
use \BitFrame\Renderer\PlatesRenderer;

require 'vendor/autoload.php';

$app = new Application;

// instantiate with custom options
$renderer = new PlatesRenderer( 
    // default template directory
    __DIR__, 

    // default template file extension 
    // (optional, default: 'tpl')
    'tpl', 

    // data to pass to the template
    // (optional, default: [])
    []
 );$renderer = new PlatesRenderer(null, 'tpl', []);

// add a directory
$renderer->addPath( 
    // template directory
    __DIR__, 

    // template directory namespace
    // (optional, default: null)
    'default'
 );

// using namespaced paths
// e.g. $output = $renderer->render('default::template_name');

Getting Started

Instantiate with Custom Options

You can specify the following arguments when creating a new instance of the object:

dir (string|null): The default templates directory. If null, you must add a directory using the addPath() method, or an exception would be thrown by methods that require path information (such as render method).
ext (string, optional): (default: 'tpl') The default templates file extension.
data (array, optional): (default: []) The default/global template data (the render method can overwrite these).

You can access the \League\Plates\Engine instance by calling the getEngine() method on a \BitFrame\Renderer\PlatesRenderer instance.

← Install Render Template →

use \BitFrame\Renderer\PlatesRenderer;

require 'vendor/autoload.php';

$renderer = new PlatesRenderer(__DIR__, 'tpl', [
    // globally available data
    'page_title' => '',
    'page_title_suffix' => ' - BitFrame'
]);

$output = $renderer->render('about', [
    // overwrite global data (for current template)
    'page_title' => 'About'
]);

Render Template

A template can be rendered by using the render method on the \BitFrame\Renderer\PlatesRenderer instance, which can have the following arguments:

tplName (string): Name of the template file to render/output.
data (array, optional): (default: []) The data that would be made available to the template file; you could supply any custom variables or overwrite existing global default ones.

← Getting Started Template Folders →

use \BitFrame\Renderer\PlatesRenderer;

require 'vendor/autoload.php';

$root_dir = __DIR__;

$renderer = new PlatesRenderer($root_dir, 'tpl', []);
$renderer->addPath($root_dir . '/admin', 'admin');

/* example#1: output template in '$root_dir' folder:
   $output = $renderer->render('home'); */

/* example#2: output template in 'admin' folder:
   $output = $renderer->render('admin::template_name'); */$paths = $renderer->getPaths(); // \BitFrame\Renderer\TemplatePath[]

// output namespaces:
echo $paths[0]->getNamespace(); // null
echo $paths[1]->getNamespace(); // 'admin'

// output paths:
echo $paths[0]->getPath(); // '/'
echo $paths[1]->getPath(); // '/admin'

// output paths via the magic __toString method:
echo $path[0]; // '/'
echo $path[1]; // '/admin'

Template Folders

\League\Plates lets us define namespaced folders that you can use to target specific folders, for example a folder containing admin-only templates could be named admin and be easily accessed using the syntax admin::template_name.

Add Paths

You may add as many paths as you like. This can be done by calling the addPath method on the \BitFrame\Renderer\PlatesRenderer instance which takes the following arguments:

path (string): The directory path to add.
namespace (string|null, optional): (default: null) Name to access the directory path by.

Get Paths

You can retrieve all the paths by calling the getPaths method on the \BitFrame\Renderer\PlatesRenderer instance. This returns an array of \BitFrame\Renderer\TemplatePath which has the following methods accessible on it:

getNamespace(): ?string
getPath(): string

← Render Template Template Variables →

use \BitFrame\Renderer\PlatesRenderer;

require 'vendor/autoload.php';

$data = ['foo' => 'bar'];

/* Passing data to constructor calls the method: 
 addDefaultParam(PlatesRenderer::TEMPLATE_ALL, $data) */
$renderer = new PlatesRenderer(__DIR__, 'tpl', $data);$renderer = new PlatesRenderer(__DIR__);

/* add data to all templates? 
 *
 * Note that the TEMPLATE_ALL constant can also be
 * accessed on a \BitFrame\Renderer\TemplateInterface instance.
 */
$renderer->addDefaultParam(PlatesRenderer::TEMPLATE_ALL, $data);

// add data to a specific template?
$renderer->addDefaultParam('template_name', $data);$renderer = new PlatesRenderer(__DIR__);

$output = $renderer->render('template_name', $data);

Template Variables

You can use the following methods on a \BitFrame\Renderer\PlatesRenderer instance to define variables for use in templates:

__construct($templateDir, $templateExt, $data)
addDefaultParam($templateName, $data)
render($templateName, $data): string

Please note that data added via the constructor will always be available to all template files. However, using addDefaultParam() you could define/overwrite data specific to a template. Also note that, shared data is assigned to a template when it's first created, meaning any conflicting data assigned afterwards to a specific template will overwrite the shared data. This is generally desired behavior.

← Template Folders About →

/**
 * The PHP League Plates Wrapper
 *
 * @author    Daniyal Hamid
 * @copyright Copyright (c) 2017-2018 Daniyal Hamid (https://designcise.com)
 *
 * @author    Zend Framework
 * @copyright Copyright (c) 2016-2017 Zend Technologies USA Inc.
 *
 * @license   MIT License and New BSD License
 */

About

Plates is a native PHP template system that helps you create and manage template files in PHP.

Plates Official GitHub

← Template Variables API →

Comments

Let us know if you have something to say or add

Changelog

Latest version 1.0.0 released on Feb 14, 2018

Feb 14, 2018

Version 1.0.0

Support to specify template variables
Support to add template namespaced paths
Support to specify default template file extension