41 | ~~~
42 |
43 | They can also be used in a [batch]({{< relref "templates/functions.md#batch-function-calls" >}}) compatible function:
44 |
45 | ~~~ php
46 |
Hello e($name, 'uppercase')
47 | ~~~
48 |
49 | ## Single method extensions
50 |
51 | Alternatively, you may choose to expose the entire extension object to the template using a single function. This can make your templates more legible and also reduce the chance of conflicts with other extensions.
52 |
53 | ~~~ php
54 | use League\Plates\Engine;
55 | use League\Plates\Extension\ExtensionInterface;
56 |
57 | class ChangeCase implements ExtensionInterface
58 | {
59 | public function register(Engine $engine)
60 | {
61 | $engine->registerFunction('case', [$this, 'getObject']);
62 | }
63 |
64 | public function getObject()
65 | {
66 | return $this;
67 | }
68 |
69 | public function upper($var)
70 | {
71 | return strtoupper($var);
72 | }
73 |
74 | public function lower($var)
75 | {
76 | return strtolower($var);
77 | }
78 | }
79 | ~~~
80 |
81 | To use this extension in your template, first call the primary function, then the secondary functions:
82 |
83 | ~~~ php
84 |
Hello, e($this->case()->upper($name))?>
85 | ~~~
86 |
87 | ## Loading extensions
88 |
89 | To enable an extension, load it into the [engine]({{< relref "engine/overview.md" >}}) object using the `loadExtension()` method.
90 |
91 | ~~~ php
92 | $engine->loadExtension(new ChangeCase());
93 | ~~~
94 |
95 | ## Accessing the engine and template
96 |
97 | It may be desirable to access the `engine` or `template` objects from within your extension. Plates makes both of these objects available to you. The engine is automatically passed to the `register()` method, and the template is assigned as a parameter on each function call.
98 |
99 | ~~~ php
100 | use League\Plates\Engine;
101 | use League\Plates\Extension\ExtensionInterface;
102 |
103 | class MyExtension implements ExtensionInterface
104 | {
105 | protected $engine;
106 | public $template; // must be public
107 |
108 | public function register(Engine $engine)
109 | {
110 | $this->engine = $engine;
111 |
112 | // Access template data:
113 | $data = $this->template->data();
114 |
115 | // Register functions
116 | // ...
117 | }
118 | }
119 | ~~~
120 |
--------------------------------------------------------------------------------
/doc/content/engine/file-extensions.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "File Extensions"
3 | linkTitle = "Engine File Extensions"
4 | [menu.main]
5 | parent = "engine"
6 | weight = 2
7 | +++
8 |
9 | Plates does not enforce a specific template file extension. By default it assumes `.php`. This file extension is automatically appended to your template names when rendered. You are welcome to change the default extension using one of the following methods.
10 |
11 | ## Constructor method
12 |
13 | ~~~ php
14 | // Create new engine and set the default file extension to ".tpl"
15 | $template = new League\Plates\Engine('/path/to/templates', 'tpl');
16 | ~~~
17 |
18 | ## Setter method
19 |
20 | ~~~ php
21 | // Sets the default file extension to ".tpl" after engine instantiation
22 | $template->setFileExtension('tpl');
23 | ~~~
24 |
25 | ## Manually assign
26 |
27 | If you prefer to manually set the file extension, simply set the default file extension to `null`.
28 |
29 | ~~~ php
30 | // Disable automatic file extensions
31 | $template->setFileExtension(null);
32 |
33 | // Render template
34 | echo $templates->render('home.php');
35 | ~~~
--------------------------------------------------------------------------------
/doc/content/engine/folders.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Folders"
3 | linkTitle = "Engine Folders"
4 | [menu.main]
5 | parent = "engine"
6 | weight = 3
7 | +++
8 |
9 | Folders make it really easy to organize and access your templates. Folders allow you to group your templates under different namespaces, each of which having their own file system path.
10 |
11 | ## Creating folders
12 |
13 | To create folders, use the `addFolder()` method:
14 |
15 | ~~~ php
16 | // Create new Plates instance
17 | $templates = new League\Plates\Engine();
18 |
19 | // Add folders
20 | $templates->addFolder('admin', '/path/to/admin/templates');
21 | $templates->addFolder('emails', '/path/to/email/templates');
22 | ~~~
23 |
24 | ## Using folders
25 |
26 | To use the folders you created within your project simply append the folder name with two colons before the template name. For example, to render a welcome email:
27 |
28 | ~~~ php
29 | $email = $templates->render('emails::welcome');
30 | ~~~
31 |
32 | This works with template functions as well, such as layouts or nested templates. For example:
33 |
34 | ~~~ php
35 | layout('shared::template') ?>
36 | ~~~
37 |
38 | ## Folder fallbacks
39 |
40 | When enabled, if a folder template is missing, Plates will automatically fallback and look for a template with the **same** name in the default folder. This can be helpful when using folders to manage themes. To enable fallbacks, simply pass `true` as the third parameter in the `addFolders()` method.
41 |
42 | ~~~ php
43 | // Create new Plates engine
44 | $templates = new \League\Plates\Engine('/path/to/default/theme');
45 |
46 | // Add themes
47 | $templates->addFolder('theme1', '/path/to/theme/1', true);
48 | $templates->addFolder('theme2', '/path/to/theme/2', true);
49 | ~~~
--------------------------------------------------------------------------------
/doc/content/engine/functions.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Functions"
3 | linkTitle = "Engine Functions"
4 | [menu.main]
5 | parent = "engine"
6 | weight = 4
7 | +++
8 |
9 | While [extensions]({{< relref "engine/extensions.md" >}}) are awesome for adding additional reusable functionality to Plates, sometimes it's easier to just create a one-off function for a specific use case. Plates makes this easy to do.
10 |
11 | ## Registering functions
12 |
13 | ~~~ php
14 | // Create new Plates engine
15 | $templates = new \League\Plates\Engine('/path/to/templates');
16 |
17 | // Register a one-off function
18 | $templates->registerFunction('uppercase', function ($string) {
19 | return strtoupper($string);
20 | });
21 | ~~~
22 |
23 | To use this function in a template, simply call it like any other function:
24 |
25 | ~~~ php
26 |
Hello e($this->uppercase($name))
27 | ~~~
28 |
29 | It can also be used in a [batch]({{< relref "templates/functions#batch-function-calls">}}) compatible function:
30 |
31 | ~~~ php
32 |
Hello e($name, 'uppercase')
33 | ~~~
34 |
--------------------------------------------------------------------------------
/doc/content/engine/overview.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Overview"
3 | linkTitle = "Engine Overview"
4 | aliases = ["/engine"]
5 | [menu.main]
6 | parent = "engine"
7 | weight = 1
8 | +++
9 |
10 | Plates uses a central object called the `Engine`, which is used to store the environment configuration, functions and extensions. It helps decouple your templates from the file system and other dependencies. For example, if you want to change the folder where your templates are stored, you can do so by simply changing the path in one location.
11 |
12 | ## Basic usage
13 |
14 | ~~~ php
15 | // Create new Plates engine
16 | $templates = new League\Plates\Engine('/path/to/templates');
17 |
18 | // Add any additional folders
19 | $templates->addFolder('emails', '/path/to/emails');
20 |
21 | // Load any additional extensions
22 | $templates->loadExtension(new League\Plates\Extension\Asset('/path/to/public'));
23 |
24 | // Create a new template
25 | $template = $templates->make('emails::welcome');
26 | ~~~
27 |
28 | ## Dependency Injection
29 |
30 | Plates is designed to be easily passed around your application and easily injected in your controllers or other application objects. Simply pass an instance of the `Engine` to any consuming objects, and then use either the `make()` method to create a new template, or the `render()` method to render it immediately. For example:
31 |
32 | ~~~ php
33 | class Controller
34 | {
35 | private $templates;
36 |
37 | public function __construct(League\Plates\Engine $templates)
38 | {
39 | $this->templates = $templates;
40 | }
41 |
42 | // Create a template object
43 | public function getIndex()
44 | {
45 | $template = $this->templates->make('home');
46 |
47 | return $template->render();
48 | }
49 |
50 | // Render a template directly
51 | public function getIndex()
52 | {
53 | return $this->templates->render('home');
54 | }
55 | }
56 | ~~~
57 |
--------------------------------------------------------------------------------
/doc/content/engine/themes.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Themes"
3 | linkTitle = "Engine Themes"
4 | [menu.main]
5 | parent = "engine"
6 | weight = 6
7 | [menu.main.params]
8 | badge = "v3.5"
9 | +++
10 |
11 | Themes provide an alternative to template path resolution that allow for a holistic approach to template overrides and fallbacks.
12 |
13 | ## Usage
14 |
15 | Given an engine configuration like:
16 |
17 | ```php
18 | use League\Plates\{Engine, Template\Theme};
19 |
20 | $plates = Engine::fromTheme(Theme::hierarchy([
21 | Theme::new('/templates/main', 'Main'), // parent
22 | Theme::new('/templates/user', 'User'), // child
23 | Theme::new('/templates/seasonal', 'Seasonal'), // child2
24 | ]));
25 | ```
26 |
27 | And a file structure like:
28 |
29 | ```
30 | templates/
31 | main/
32 | layout.php
33 | home.php
34 | header.php
35 | user/
36 | layout.php
37 | header.php
38 | seasonal/
39 | header.php
40 | ```
41 |
42 | The following looks ups, *regardless of where they are called from*, would resolve to the following files:
43 |
44 | ```php
45 | $templates->render('home'); // templates/main/home.php
46 | $templates->render('layout'); // templates/user/layout.php
47 | $templates->render('header'); // templates/seasonal/header.php
48 | ```
49 |
50 | All paths are resolved from the last child to the first parent allowing a hierarchy of overrides.
51 |
52 | ## Differences from Directory and Folders
53 |
54 | This logic is used **instead of** the directories and folders feature since they are distinct in nature, and combining the logic isn't obvious on how the features should stack.
55 |
56 | Creating an engine with one theme is functionally equivalent to using just a directory with no folders.
57 |
58 | The fallback functionality is a bit different however since with folders, it's *opt in*, you need to prefix the template name with the folder name. With themes, all template names implicitly will be resolved and fallback according to the hierarchy setup.
59 |
60 | ## Additional Customization
61 |
62 | This functionality is powered by the `League\Plates\Template\ResolveTemplatePath` interface. If you'd prefer a more complex or specific path resolution, you can just implement your own and assign it to the engine instance with:
63 |
64 | ```php
65 | $plates = Engine::withResolveTemplatePath(new MyCustomResolveTemplatePath());
66 | ```
67 |
68 | The resolve template path should always resolve a string that represents a verified path on the filesystem or throw a TemplateNotFound exception.
69 |
--------------------------------------------------------------------------------
/doc/content/extensions/_index.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Extensions"
3 | [menu.main]
4 | identifier = "extensions"
5 | weight = 4
6 | +++
--------------------------------------------------------------------------------
/doc/content/extensions/asset.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Asset"
3 | [menu.main]
4 | parent = "extensions"
5 | weight = 1
6 | +++
7 |
8 | The asset extension can be used to quickly create "cache busted" asset URLs in your templates. This is particularly helpful for aggressively cached files that can potentially change in the future, such as CSS files, JavaScript files and images. It works by appending the timestamp of the file's last update to its URL. For example, `/css/all.css` becomes `/css/all.1373577602.css`. As long as the file does not change, the timestamp remains the same and caching occurs. However, if the file is changed, a new URL is automatically generated with a new timestamp, and visitors receive the new file.
9 |
10 | ## Installing the asset extension
11 |
12 | The asset extension comes packaged with Plates but is not enabled by default, as it requires extra parameters passed to it at instantiation.
13 |
14 | ~~~ php
15 | // Load asset extension
16 | $engine->loadExtension(new League\Plates\Extension\Asset('/path/to/public/assets/', true));
17 | ~~~
18 |
19 | The first constructor parameter is the file system path of the assets directory. The second is an optional `boolean` parameter that if set to true uses the filename caching method (ie. `file.1373577602.css`) instead of the default query string method (ie. `file.css?v=1373577602`).
20 |
21 | ## Filename caching
22 |
23 | To make filename caching work, some URL rewriting is required:
24 |
25 | ### Apache example
26 | ~~~ php
27 |
28 | RewriteCond %{REQUEST_FILENAME} !-f
29 | RewriteCond %{REQUEST_FILENAME} !-d
30 | RewriteRule ^(.+)\.(\d+)\.(js|css|png|jpg|gif)$ $1.$3 [L]
31 |
32 | ~~~
33 |
34 | ### Nginx example
35 |
36 | ~~~ php
37 | location ~* (.+)\.(?:\d+)\.(js|css|png|jpg|jpeg|gif)$ {
38 | try_files $uri $1.$2;
39 | }
40 | ~~~
41 |
42 | ## Using the asset extension
43 |
44 | ~~~ php
45 |
46 |
47 | Asset Extension Example
48 |
49 |
50 |
51 |
52 |
53 |
54 |
55 |
56 |
57 | ~~~
58 |
--------------------------------------------------------------------------------
/doc/content/extensions/community.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Community"
3 | [menu.main]
4 | parent = "extensions"
5 | weight = 3
6 | +++
7 |
8 | This is a list of all the known community extensions for the Plates library. Please feel free to submit a [Pull Request](https://github.com/thephpleague/plates) to add your extension to this list.
9 |
10 | - [Laravel Provider](https://github.com/franzliedke/laravel-plates)
11 | - [Attributes Rendering](https://github.com/RobinDev/platesAttributes) - Transforms arrays into html tag attributes.
12 | - [Includer](https://github.com/odahcam/plates-includer) - Include your assets in an expert way.
13 | - [Tapestry](https://github.com/tapestry-cloud/tapestry) - A blog aware, Plates based static site generator.
14 | - [Plates Local Assets Copy Extension](https://github.com/basteyy/plates-local-assets-copy) - An extension for copying remote assets (files) to your local storage.
15 |
--------------------------------------------------------------------------------
/doc/content/extensions/uri.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "URI"
3 | [menu.main]
4 | parent = "extensions"
5 | weight = 2
6 | +++
7 |
8 | The URI extension is designed to make URI checks within templates easier. The most common use is marking the current page in a menu as "selected". It only has one function, `uri()`, but can do a number of helpful tasks depending on the parameters passed to it.
9 |
10 | ## Installing the URI extension
11 |
12 | The URI extension comes packaged with Plates but is not enabled by default, as it requires an extra parameter passed to it at instantiation.
13 |
14 | ~~~ php
15 | // Load URI extension using global variable
16 | $engine->loadExtension(new League\Plates\Extension\URI($_SERVER['PATH_INFO']));
17 |
18 | // Load URI extension using a HttpFoundation's request object
19 | $engine->loadExtension(new League\Plates\Extension\URI($request->getPathInfo()));
20 | ~~~
21 |
22 | ## URI example
23 |
24 | ~~~ php
25 |
31 | ~~~
32 |
33 | ## Using the URI extension
34 |
35 | Get the whole URI.
36 |
37 | ~~~ php
38 | uri()?>
39 | ~~~
40 |
41 | Get a specified segment of the URI.
42 |
43 | ~~~ php
44 | uri(1)?>
45 | ~~~
46 |
47 | Check if a specific segment of the URI (first parameter) equals a given string (second parameter). Returns `true` on success or `false` on failure.
48 |
49 | ~~~ php
50 | uri(1, 'home')): ?>
51 | ~~~
52 |
53 | Check if a specific segment of the URI (first parameter) equals a given string (second parameter). Returns string (third parameter) on success or `false` on failure.
54 |
55 | ~~~ php
56 | uri(1, 'home', 'success')?>
57 | ~~~
58 |
59 | Check if a specific segment of the URI (first parameter) equals a given string (second parameter). Returns string (third parameter) on success or string (fourth parameter) on failure.
60 |
61 | ~~~ php
62 | uri(1, 'home', 'success', 'fail')?>
63 | ~~~
64 |
65 | Check if a regular expression string matches the current URI. Returns `true` on success or `false` on failure.
66 |
67 | ~~~ php
68 | uri('/home')): ?>
69 | ~~~
70 |
71 | Check if a regular expression string (first parameter) matches the current URI. Returns string (second parameter) on success or `false` on failure.
72 |
73 | ~~~ php
74 | uri('/home', 'success')?>
75 | ~~~
76 |
77 | Check if a regular expression string (first parameter) matches the current URI. Returns string (second parameter) on success or string (third parameter) on failure.
78 |
79 | ~~~ php
80 | uri('/home', 'success', 'fail')?>
81 | ~~~
--------------------------------------------------------------------------------
/doc/content/getting-started/_index.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Getting Started"
3 | [menu.main]
4 | identifier = "getting-started"
5 | weight = 1
6 | +++
--------------------------------------------------------------------------------
/doc/content/getting-started/installation.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Installation"
3 | [menu.main]
4 | parent = "getting-started"
5 | weight = 3
6 | +++
7 |
8 | ## Using Composer
9 |
10 | Plates is available on [Packagist](https://packagist.org/packages/league/plates) and can be installed using [Composer](https://getcomposer.org/). This can be done by running the following command or by updating your `composer.json` file.
11 |
12 | ~~~ bash
13 | composer require league/plates
14 | ~~~
15 |
16 | {{< code-filename composer.json >}}
17 | ~~~ javascript
18 | {
19 | "require": {
20 | "league/plates": "3.*"
21 | }
22 | }
23 | ~~~
24 |
25 | Be sure to also include your Composer autoload file in your project:
26 |
27 | ~~~ php
28 | require 'vendor/autoload.php';
29 | ~~~
30 |
31 | ## Downloading .zip file
32 |
33 | This project is also available for download as a `.zip` file on GitHub. Visit the [releases page](https://github.com/thephpleague/plates/releases), select the version you want, and click the "Source code (zip)" download button.
--------------------------------------------------------------------------------
/doc/content/getting-started/simple-example.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Simple Example"
3 | [menu.main]
4 | parent = "getting-started"
5 | weight = 2
6 | +++
7 |
8 | Here is a simple example of how to use Plates. We will assume the following directory stucture:
9 |
10 | ~~~
11 | `-- path
12 | `-- to
13 | `-- templates
14 | |-- template.php
15 | |-- profile.php
16 | ~~~
17 |
18 | ## Within your controller
19 |
20 | ~~~ php
21 | // Create new Plates instance
22 | $templates = new League\Plates\Engine('/path/to/templates');
23 |
24 | // Render a template
25 | echo $templates->render('profile', ['name' => 'Jonathan']);
26 | ~~~
27 |
28 | ## The page template
29 |
30 | {{< code-filename profile.php >}}
31 | ~~~ php
32 | layout('template', ['title' => 'User Profile']) ?>
33 |
34 |
User Profile
35 |
Hello, e($name)?>
36 | ~~~
37 |
38 | ## The layout template
39 |
40 | {{< code-filename template.php >}}
41 | ~~~ php
42 |
43 |
44 | <?=$this->e($title)?>
45 |
46 |
47 | section('content')?>
48 |
49 |
50 | ~~~
--------------------------------------------------------------------------------
/doc/content/templates/_index.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Templates"
3 | [menu.main]
4 | identifier = "templates"
5 | weight = 3
6 | +++
--------------------------------------------------------------------------------
/doc/content/templates/data.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Data"
3 | linkTitle = "Templates Data"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 2
7 | +++
8 |
9 | It's very common to share application data (variables) with a template. Data can be whatever you want: strings, arrays, objects, etc. Plates allows you set both template specific data as well as shared template data.
10 |
11 | ## Assign data
12 |
13 | Assigning data is done from within your application code, such as a controller. There are a number of ways to assign the data, depending on how you structure your objects.
14 |
15 | ~~~ php
16 | // Create new Plates instance
17 | $templates = new League\Plates\Engine('/path/to/templates');
18 |
19 | // Assign via the engine's render method
20 | echo $templates->render('profile', ['name' => 'Jonathan']);
21 |
22 | // Assign via the engine's make method
23 | $template = $templates->make('profile', ['name' => 'Jonathan']);
24 |
25 | // Assign directly to a template object
26 | $template = $templates->make('profile');
27 | $template->data(['name' => 'Jonathan']);
28 | ~~~
29 |
30 | ## Accessing data
31 |
32 | Template data is available as locally scoped variables at the time of rendering. Continuing with the example above, here is how you would [escape]({{< relref "templates/escaping.md" >}}) and output the "name" value in a template:
33 |
34 | ~~~ php
35 |
Hello e($name)?>
36 | ~~~
37 |
38 |
Prior to Plates 3.0, variables were accessed using the $this pseudo-variable. This is no longer possible. Use the locally scoped variables instead.
39 |
40 | ## Preassigned and shared data
41 |
42 | If you have data that you want assigned to a specific template each time that template is rendered throughout your application, the `addData()` function can help organize that code in one place.
43 |
44 | ~~~ php
45 | $templates->addData(['name' => 'Jonathan'], 'emails::welcome');
46 | ~~~
47 |
48 | You can pressaign data to more than one template by passing an array of templates:
49 |
50 | ~~~ php
51 | $templates->addData(['name' => 'Jonathan'], ['login', 'template']);
52 | ~~~
53 |
54 | To assign data to ALL templates, simply omit the second parameter:
55 |
56 | ~~~ php
57 | $templates->addData(['name' => 'Jonathan']);
58 | ~~~
59 |
60 | Keep in mind that shared data is assigned to a template when it's first created, meaning any conflicting data assigned that's afterwards to a specific template will overwrite the shared data. This is generally desired behavior.
61 |
--------------------------------------------------------------------------------
/doc/content/templates/escaping.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Escaping"
3 | linkTitle = "Templates Escaping"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 8
7 | +++
8 |
9 | Escaping is a form of [data filtering](http://www.phptherightway.com/#data_filtering) which sanitizes unsafe, user supplied input prior to outputting it as HTML. Plates provides two shortcuts to the `htmlspecialchars()` function.
10 |
11 | ## Escaping example
12 |
13 | ~~~ php
14 |
Hello, escape($name)?>
15 |
16 |
17 |
Hello, e($name)?>
18 | ~~~
19 |
20 | ## Batch function calls
21 |
22 | The escape functions also support [batch]({{< relref "templates/functions.md#batch-function-calls" >}}) function calls, which allow you to apply multiple functions, including native PHP functions, to a variable at one time.
23 |
24 | ~~~ php
25 |
It's VERY important to always double quote HTML attributes that contain escaped variables, otherwise your template will still be open to injection attacks.
31 |
32 | Some [libraries](http://framework.zend.com/manual/2.1/en/modules/zend.escaper.escaping-html-attributes.html) go as far as having a special function for escaping HTML attributes. However, this is somewhat redundant considering that if a developer forgets to properly quote an HTML attribute, they will likely also forget to use this special function. Here is how you properly escape HTML attributes:
33 |
34 | ~~~ php
35 |
36 |
37 |
38 |
39 |
40 |
41 |
42 | e($name)?>>
43 | ~~~
44 |
45 | ## Automatic escaping
46 |
47 | Probably the biggest drawbacks to native PHP templates is the inability to auto-escape variables properly. Template languages like Twig and Smarty can identify "echoed" variables during a parsing stage and automatically escape them. This cannot be done in native PHP as the language does not offer overloading functionality for it's output functions (ie. `print` and `echo`).
48 |
49 | Don't worry, escaping can still be done safely, it just means you are responsible for manually escaping each variable on output. Consider creating a snippet for one of the above, built-in escaping functions to make this process easier.
50 |
--------------------------------------------------------------------------------
/doc/content/templates/functions.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Functions"
3 | linkTitle = "Templates Functions"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 3
7 | +++
8 |
9 | Template functions in Plates are accessed using the `$this` pseudo-variable.
10 |
11 | ~~~ php
12 |
Hello, escape($name)?>
13 | ~~~
14 |
15 |
16 | ## Custom fuctions
17 |
18 | In addition to the functions included with Plates, it's also possible to add [one-off functions]({{< relref "engine/functions.md" >}}), or even groups of functions, known as [extensions]({{< relref "engine/extensions.md" >}}).
19 |
20 | ## Batch function calls
21 |
22 | Sometimes you need to apply more than function to a variable in your templates. This can become somewhat illegible. The `batch()` function helps by allowing you to apply multiple functions, including native PHP functions, to a variable at one time.
23 |
24 | ~~~ php
25 |
26 |
30 | ~~~
31 |
32 | The [escape]({{< relref "templates/escaping.md" >}}) functions also support batch function calls.
33 |
34 | ~~~ php
35 |
Welcome e($name, 'strip_tags|strtoupper')?>
36 | ~~~
37 |
38 | The batch functions works well for "piped" functions that accept one parameter, modify it, and then return it. It's important to note that they execute functions left to right and will favour extension functions over native PHP functions if there are conflicts.
39 |
40 | ~~~ php
41 |
42 | batch('Jonathan', 'escape|strtolower|strtoupper')?>
43 |
44 |
45 | batch('Jonathan', 'escape|strtoupper|strtolower')?>
46 | ~~~
47 |
--------------------------------------------------------------------------------
/doc/content/templates/inheritance.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Inheritance"
3 | linkTitle = "Templates Inheritance"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 7
7 | +++
8 |
9 | By combining [layouts]({{< relref "templates/layouts.md" >}}) and [sections]({{< relref "templates/sections.md" >}}), Plates allows you to "build up" your pages using predefined sections. This is best understand using an example:
10 |
11 | ## Inheritance example
12 |
13 | The following example illustrates a pretty standard website. Start by creating a site template, which includes your header and footer as well as any predefined content [sections]({{< relref "templates/sections.md" >}}). Notice how Plates makes it possible to even set default section content, in the event that a page doesn't define it.
14 |
15 | {{< code-filename template.php >}}
16 |
17 | ~~~ php
18 |
19 |
20 | <?=$this->e($title)?>
21 |
22 |
23 |
24 |
25 |
26 |
62 | stop() ?>
63 | ~~~
64 |
--------------------------------------------------------------------------------
/doc/content/templates/layouts.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Layouts"
3 | linkTitle = "Templates Layouts"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 5
7 | +++
8 |
9 | The `layout()` function allows you to define a layout template that a template will implement. It's like having separate header and footer templates in one file.
10 |
11 | ## Define a layout
12 |
13 | The `layout()` function can be called anywhere in a template, since the layout template is actually rendered second. Typically it's placed at the top of the file.
14 |
15 | ~~~ php
16 | layout('template') ?>
17 |
18 |
User Profile
19 |
Hello, e($name)?>
20 | ~~~
21 |
22 | This function also works with [folders]({{< relref "engine/folders.md" >}}):
23 |
24 | ~~~ php
25 | layout('shared::template') ?>
26 | ~~~
27 |
28 | ## Assign data
29 |
30 | To assign data (variables) to a layout template, pass them as an array to the `layout()` function. This data will then be available as locally scoped variables within the layout template.
31 |
32 | ~~~ php
33 | layout('template', ['title' => 'User Profile']) ?>
34 | ~~~
35 |
36 | ## Accessing the content
37 |
38 | To access the rendered template content within the layout, use the `section()` function, passing `'content'` as the section name. This will return all outputted content from the template that hasn't been defined in a [section]({{< relref "templates/sections.md" >}}).
39 |
40 | ~~~ php
41 |
42 |
43 | <?=$this->e($title)?>
44 |
45 |
46 |
47 | section('content')?>
48 |
49 |
50 |
51 | ~~~
52 |
53 | ## Stacked layouts
54 |
55 | Plates allows stacking of layouts, allowing even further simplification and organization of templates. Instead of just using one main layout, it's possible to break templates into more specific layouts, which themselves implement a main layout. Consider this example:
56 |
57 | ### The main site layout
58 |
59 | {{< code-filename template.php >}}
60 |
61 | ~~~ php
62 |
63 |
64 | <?=$this->e($title)?>
65 |
66 |
67 |
68 | section('content')?>
69 |
70 |
71 |
72 | ~~~
73 |
74 | ### The blog layout
75 |
76 | {{< code-filename blog.php >}}
77 |
78 | ~~~ php
79 | layout('template', ['title' => $title]) ?>
80 |
81 |
101 |
102 | e($article->content)?>
103 |
104 | ~~~
105 |
--------------------------------------------------------------------------------
/doc/content/templates/nesting.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Nesting"
3 | linkTitle = "Templates Nesting"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 4
7 | +++
8 |
9 | Including another template into the current template is done using the `insert()` function:
10 |
11 | ~~~ php
12 | insert('partials/header') ?>
13 |
14 |
Your content.
15 |
16 | insert('partials/footer') ?>
17 | ~~~
18 |
19 | The `insert()` function also works with [folders]({{< relref "engine/folders.md" >}}):
20 |
21 | ~~~ php
22 | insert('partials::header') ?>
23 | ~~~
24 |
25 | ## Alternative syntax
26 |
27 | The `insert()` function automatically outputs the rendered template. If you prefer to manually output the response, use the `fetch()` function instead:
28 |
29 | ~~~ php
30 | fetch('partials/header')?>
31 | ~~~
32 |
33 | ## Assign data
34 |
35 | To assign data (variables) to a nested template, pass them as an array to the `insert()` or `fetch()` functions. This data will then be available as locally scoped variables within the nested template.
36 |
37 | ~~~ php
38 | insert('partials/header', ['name' => 'Jonathan']) ?>
39 |
40 |
Your content.
41 |
42 | insert('partials/footer') ?>
43 | ~~~
44 |
--------------------------------------------------------------------------------
/doc/content/templates/overview.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Overview"
3 | linkTitle = "Templates Overview"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 1
7 | +++
8 |
9 | Plates templates are very simple PHP objects. Generally you'll want to create these using the two factory methods, `make()` and `render()`, in the [engine]({{< relref "engine/overview.md" >}}). For example:
10 |
11 | ~~~ php
12 | // Create new Plates instance
13 | $templates = new League\Plates\Engine('/path/to/templates');
14 |
15 | // Render a template in a subdirectory
16 | echo $templates->render('partials/header');
17 |
18 | // Render a template
19 | echo $templates->render('profile', ['name' => 'Jonathan']);
20 | ~~~
21 |
22 | For more information about how Plates is designed to be easily added to your application, see the section on [dependency injection]({{< relref "engine/overview.md#dependency-injection" >}}).
23 |
24 | ## Manually creating templates
25 |
26 | It's also possible to create templates manually. The only dependency they require is an instance of the [engine]({{< relref "engine/overview.md" >}}) object. For example:
27 |
28 | ~~~ php
29 | // Create new Plates instance
30 | $templates = new League\Plates\Engine('/path/to/templates');
31 |
32 | // Create a new template
33 | $template = new League\Plates\Template\Template($templates, 'profile');
34 |
35 | // Render the template
36 | echo $template->render(['name' => 'Jonathan']);
37 |
38 | // You can also render the template using the toString() magic method
39 | echo $template;
40 | ~~~
41 |
42 | ## Check if a template exists
43 |
44 | When dynamically loading templates, you may need to check if they exist. This can be done using the engine's `exists()` method:
45 |
46 | ~~~ php
47 | if ($templates->exists('articles::beginners_guide')) {
48 | // It exists!
49 | }
50 | ~~~
51 |
52 | You can also run this check on an existing template:
53 |
54 | ~~~ php
55 | if ($template->exists()) {
56 | // It exists!
57 | }
58 | ~~~
59 |
60 | ## Get a template path
61 |
62 | To get a template path from its name, use the engine's `path()` method:
63 |
64 | ~~~ php
65 | $path = $templates->path('articles::beginners_guide');
66 | ~~~
67 |
68 | You can also get the path from an existing template:
69 |
70 | ~~~ php
71 | $path = $template->path();
72 | ~~~
73 |
--------------------------------------------------------------------------------
/doc/content/templates/sections.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Sections"
3 | linkTitle = "Templates Sections"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 6
7 | +++
8 |
9 | The `start()` and `stop` functions allow you to build sections (or blocks) of content within your template, and instead of them being rendered directly, they are saved for use elsewhere. For example, in your [layout]({{< relref "templates/layouts.md" >}}) template.
10 |
11 | ## Creating sections
12 |
13 | You define the name of the section with the `start()` function. To end a section call the `stop()` function.
14 |
15 | ~~~ php
16 | start('welcome') ?>
17 |
18 |
Welcome!
19 |
Hello e($name)?>
20 |
21 | stop() ?>
22 | ~~~
23 |
24 | ## Stacking section content
25 |
26 | By default, when you render a section its content will overwrite any existing content for that section. However, it's possible to append/prepend (or stack) the content instead using the `push()` or `unshift()` method respectively. This can be useful for specifying any JavaScript libraries or CSS files required by your child views.
27 |
28 | ~~~ php
29 | push('scripts') ?>
30 |
31 | end() ?>
32 |
33 | unshift('styles') ?>
34 |
35 | end() ?>
36 | ~~~
37 |
38 |
The end() function is simply an alias of stop(). These functions can be used interchangeably.
39 |
40 | ## Accessing section content
41 |
42 | Access rendered section content using the name you assigned in the `start()` method. This variable can be accessed from the current template and layout templates using the `section()` function.
43 |
44 | ~~~ php
45 | section('welcome')?>
46 | ~~~
47 |
48 |
Prior to Plates 3.0, accessing template content was done using either the content() or child() functions. For consistency with sections, this is no longer possible.
49 |
50 | ## Default section content
51 |
52 | In situations where a page doesn't implement a particular section, it's helpful to assign default content. There are a couple ways to do this:
53 |
54 | ### Defining it inline
55 |
56 | If the default content can be defined in a single line of code, it's best to simply pass it as the second parameter of the `section()` function.
57 |
58 | ~~~ php
59 |
62 | ~~~
63 |
64 | ### Use an if statement
65 |
66 | If the default content requires more than a single line of code, it's best to use a simple if statement to check if a section exists, and otherwise display the default.
67 |
68 | ~~~ php
69 |
82 | ~~~
83 |
84 |
--------------------------------------------------------------------------------
/doc/content/templates/syntax.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Syntax"
3 | linkTitle = "Templates Syntax"
4 | [menu.main]
5 | parent = "templates"
6 | weight = 9
7 | +++
8 |
9 | While the actual syntax you use in your templates is entirely your choice (it's just PHP after all), we suggest the following syntax guidelines to help keep templates clean and legible.
10 |
11 | ## Guidelines
12 |
13 | - Always use HTML with inline PHP. Never use blocks of PHP.
14 | - Always escape potentially dangerous variables prior to outputting using the built-in escape functions. More on escaping [here]({{< relref "templates/escaping.md" >}}).
15 | - Always use the short echo syntax (`layout('template', ['title' => 'User Profile']) ?>
30 |
31 |
33 | ?>){kind=logo}
54 |
55 |
56 |
57 | ~~~
58 |
--------------------------------------------------------------------------------
/doc/content/extensions/community.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "Community"
3 | [menu.main]
4 | parent = "extensions"
5 | weight = 3
6 | +++
7 |
8 | This is a list of all the known community extensions for the Plates library. Please feel free to submit a [Pull Request](https://github.com/thephpleague/plates) to add your extension to this list.
9 |
10 | - [Laravel Provider](https://github.com/franzliedke/laravel-plates)
11 | - [Attributes Rendering](https://github.com/RobinDev/platesAttributes) - Transforms arrays into html tag attributes.
12 | - [Includer](https://github.com/odahcam/plates-includer) - Include your assets in an expert way.
13 | - [Tapestry](https://github.com/tapestry-cloud/tapestry) - A blog aware, Plates based static site generator.
14 | - [Plates Local Assets Copy Extension](https://github.com/basteyy/plates-local-assets-copy) - An extension for copying remote assets (files) to your local storage.
15 |
--------------------------------------------------------------------------------
/doc/content/extensions/uri.md:
--------------------------------------------------------------------------------
1 | +++
2 | title = "URI"
3 | [menu.main]
4 | parent = "extensions"
5 | weight = 2
6 | +++
7 |
8 | The URI extension is designed to make URI checks within templates easier. The most common use is marking the current page in a menu as "selected". It only has one function, `uri()`, but can do a number of helpful tasks depending on the parameters passed to it.
9 |
10 | ## Installing the URI extension
11 |
12 | The URI extension comes packaged with Plates but is not enabled by default, as it requires an extra parameter passed to it at instantiation.
13 |
14 | ~~~ php
15 | // Load URI extension using global variable
16 | $engine->loadExtension(new League\Plates\Extension\URI($_SERVER['PATH_INFO']));
17 |
18 | // Load URI extension using a HttpFoundation's request object
19 | $engine->loadExtension(new League\Plates\Extension\URI($request->getPathInfo()));
20 | ~~~
21 |
22 | ## URI example
23 |
24 | ~~~ php
25 | 
37 |
38 |
39 | 
25 |
26 | 
38 |
39 | 
50 |
51 | {{ end }}
52 | {{ .Site.Title }}
53 | {{ .Site.Params.tagline }}
54 |
55 |
56 | Presented by The League of Extraordinary Packages
57 |
58 |