외부 코드를 Composer 기반으로 변경
This commit is contained in:
+61
@@ -0,0 +1,61 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/data/
|
||||
title: Data
|
||||
---
|
||||
|
||||
Data
|
||||
====
|
||||
|
||||
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.
|
||||
|
||||
## Assign data
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
// Create new Plates instance
|
||||
$templates = new League\Plates\Engine('/path/to/templates');
|
||||
|
||||
// Assign via the engine's render method
|
||||
echo $templates->render('profile', ['name' => 'Jonathan']);
|
||||
|
||||
// Assign via the engine's make method
|
||||
$template = $templates->make('profile', ['name' => 'Jonathan']);
|
||||
|
||||
// Assign directly to a template object
|
||||
$template = $templates->make('profile');
|
||||
$template->data(['name' => 'Jonathan']);
|
||||
~~~
|
||||
|
||||
## Accessing data
|
||||
|
||||
Template data is available as locally scoped variables at the time of rendering. Continuing with the example above, here is how you would [escape](/templates/escaping/) and output the "name" value in a template:
|
||||
|
||||
~~~ php
|
||||
<p>Hello <?=$this->e($name)?></p>
|
||||
~~~
|
||||
|
||||
<p class="message-notice">Prior to Plates 3.0, variables were accessed using the <code>$this</code> pseudo-variable. This is no longer possible. Use the locally scoped variables instead.</p>
|
||||
|
||||
## Preassigned and shared data
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
$templates->addData(['name' => 'Jonathan'], 'emails::welcome');
|
||||
~~~
|
||||
|
||||
You can pressaign data to more than one template by passing an array of templates:
|
||||
|
||||
~~~ php
|
||||
$templates->addData(['name' => 'Jonathan'], ['login', 'template']);
|
||||
~~~
|
||||
|
||||
To assign data to ALL templates, simply omit the second parameter:
|
||||
|
||||
~~~ php
|
||||
$templates->addData(['name' => 'Jonathan']);
|
||||
~~~
|
||||
|
||||
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.
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/escaping/
|
||||
title: Escaping
|
||||
---
|
||||
|
||||
Escaping
|
||||
========
|
||||
|
||||
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.
|
||||
|
||||
## Escaping example
|
||||
|
||||
~~~ php
|
||||
<h1>Hello, <?=$this->escape($name)?></h1>
|
||||
|
||||
<!-- Using the alternative, shorthand function -->
|
||||
<h1>Hello, <?=$this->e($name)?></h1>
|
||||
~~~
|
||||
|
||||
## Batch function calls
|
||||
|
||||
The escape functions also support [batch](/templates/functions/#batch-function-calls) function calls, which allow you to apply multiple functions, including native PHP functions, to a variable at one time.
|
||||
|
||||
~~~ php
|
||||
<p>Welcome <?=$this->e($name, 'strip_tags|strtoupper')?></p>
|
||||
~~~
|
||||
|
||||
## Escaping HTML attributes
|
||||
|
||||
<p class="message-notice">It's VERY important to always double quote HTML attributes that contain escaped variables, otherwise your template will still be open to injection attacks.</p>
|
||||
|
||||
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:
|
||||
|
||||
~~~ php
|
||||
<!-- Good -->
|
||||
<img src="portrait.jpg" alt="<?=$this->e($name)?>">
|
||||
|
||||
<!-- BAD -->
|
||||
<img src="portrait.jpg" alt='<?=$this->e($name)?>'>
|
||||
|
||||
<!-- BAD -->
|
||||
<img src="portrait.jpg" alt=<?=$this->e($name)?>>
|
||||
~~~
|
||||
|
||||
## Automatic escaping
|
||||
|
||||
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`).
|
||||
|
||||
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.
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/functions/
|
||||
title: Functions
|
||||
---
|
||||
|
||||
Functions
|
||||
=========
|
||||
|
||||
Template functions in Plates are accessed using the `$this` pseudo-variable.
|
||||
|
||||
~~~ php
|
||||
<p>Hello, <?=$this->escape($name)?></p>
|
||||
~~~
|
||||
|
||||
|
||||
## Custom fuctions
|
||||
|
||||
In addition to the functions included with Plates, it's also possible to add [one-off functions](/engine/functions/), or even groups of functions, known as [extensions](/engine/extensions/).
|
||||
|
||||
## Batch function calls
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<!-- Example without using batch -->
|
||||
<p>Welcome <?=$this->escape(strtoupper(strip_tags($name)))?></p>
|
||||
|
||||
<!-- Example using batch -->
|
||||
<p>Welcome <?=$this->batch($name, 'strip_tags|strtoupper|escape')?></p>
|
||||
~~~
|
||||
|
||||
The [escape](/templates/escaping/) functions also support batch function calls.
|
||||
|
||||
~~~ php
|
||||
<p>Welcome <?=$this->e($name, 'strip_tags|strtoupper')?></p>
|
||||
~~~
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<!-- Will output: JONATHAN -->
|
||||
<?=$this->batch('Jonathan', 'escape|strtolower|strtoupper')?>
|
||||
|
||||
<!-- Will output: jonathan -->
|
||||
<?=$this->batch('Jonathan', 'escape|strtoupper|strtolower')?>
|
||||
~~~
|
||||
+73
@@ -0,0 +1,73 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/
|
||||
title: Templates
|
||||
---
|
||||
|
||||
Templates
|
||||
=========
|
||||
|
||||
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](/engine/). For example:
|
||||
|
||||
~~~ php
|
||||
// Create new Plates instance
|
||||
$templates = new League\Plates\Engine('/path/to/templates');
|
||||
|
||||
// Render a template in a subdirectory
|
||||
echo $templates->render('partials/header');
|
||||
|
||||
// Render a template
|
||||
echo $templates->render('profile', ['name' => 'Jonathan']);
|
||||
~~~
|
||||
|
||||
For more information about how Plates is designed to be easily added to your application, see the section on [dependency injection](/engine/#dependency-injection).
|
||||
|
||||
## Manually creating templates
|
||||
|
||||
It's also possible to create templates manually. The only dependency they require is an instance of the [engine](/engine/) object. For example:
|
||||
|
||||
~~~ php
|
||||
// Create new Plates instance
|
||||
$templates = new League\Plates\Engine('/path/to/templates');
|
||||
|
||||
// Create a new template
|
||||
$template = new League\Plates\Template\Template($templates, 'profile');
|
||||
|
||||
// Render the template
|
||||
echo $template->render(['name' => 'Jonathan']);
|
||||
|
||||
// You can also render the template using the toString() magic method
|
||||
echo $template;
|
||||
~~~
|
||||
|
||||
## Check if a template exists
|
||||
|
||||
When dynamically loading templates, you may need to check if they exist. This can be done using the engine's `exists()` method:
|
||||
|
||||
~~~ php
|
||||
if ($templates->exists('articles::beginners_guide')) {
|
||||
// It exists!
|
||||
}
|
||||
~~~
|
||||
|
||||
You can also run this check on an existing template:
|
||||
|
||||
~~~ php
|
||||
if ($template->exists()) {
|
||||
// It exists!
|
||||
}
|
||||
~~~
|
||||
|
||||
## Get a template path
|
||||
|
||||
To get a template path from its name, use the engine's `path()` method:
|
||||
|
||||
~~~ php
|
||||
$path = $templates->path('articles::beginners_guide');
|
||||
~~~
|
||||
|
||||
You can also get the path from an existing template:
|
||||
|
||||
~~~ php
|
||||
$path = $template->path();
|
||||
~~~
|
||||
@@ -0,0 +1,63 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/inheritance/
|
||||
title: Inheritance
|
||||
---
|
||||
|
||||
Inheritance
|
||||
===========
|
||||
|
||||
By combining [layouts](/templates/layouts/) and [sections](/templates/sections/), Plates allows you to "build up" your pages using predefined sections. This is best understand using an example:
|
||||
|
||||
|
||||
## Inheritance example
|
||||
|
||||
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](/templates/sections/). Notice how Plates makes it possible to even set default section content, in the event that a page doesn't define it.
|
||||
|
||||
<div class="filename">template.php</div>
|
||||
~~~ php
|
||||
<html>
|
||||
<head>
|
||||
<title><?=$this->e($title)?></title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<img src="logo.png">
|
||||
|
||||
<div id="page">
|
||||
<?=$this->section('page')?>
|
||||
</div>
|
||||
|
||||
<div id="sidebar">
|
||||
<?php if ($this->section('sidebar')): ?>
|
||||
<?=$this->section('sidebar')?>
|
||||
<?php else: ?>
|
||||
<?=$this->fetch('default-sidebar')?>
|
||||
<?php endif ?>
|
||||
</div>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
~~~
|
||||
|
||||
With the template defined, any page can now "implement" this [layout](/templates/layouts/). Notice how each section of content is defined between the `start()` and `end()` functions.
|
||||
|
||||
<div class="filename">profile.php</div>
|
||||
~~~ php
|
||||
<?php $this->layout('template', ['title' => 'User Profile']) ?>
|
||||
|
||||
<?php $this->start('page') ?>
|
||||
<h1>Welcome!</h1>
|
||||
<p>Hello <?=$this->e($name)?></p>
|
||||
<?php $this->stop() ?>
|
||||
|
||||
<?php $this->start('sidebar') ?>
|
||||
<ul>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
</ul>
|
||||
<?php $this->stop() ?>
|
||||
~~~
|
||||
+102
@@ -0,0 +1,102 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/layouts/
|
||||
title: Layouts
|
||||
---
|
||||
|
||||
Layouts
|
||||
=======
|
||||
|
||||
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.
|
||||
|
||||
## Define a layout
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<?php $this->layout('template') ?>
|
||||
|
||||
<h1>User Profile</h1>
|
||||
<p>Hello, <?=$this->e($name)?></p>
|
||||
~~~
|
||||
|
||||
This function also works with [folders](/engine/folders/):
|
||||
|
||||
~~~ php
|
||||
<?php $this->layout('shared::template') ?>
|
||||
~~~
|
||||
|
||||
## Assign data
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<?php $this->layout('template', ['title' => 'User Profile']) ?>
|
||||
~~~
|
||||
|
||||
## Accessing the content
|
||||
|
||||
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](/templates/sections/).
|
||||
|
||||
~~~ php
|
||||
<html>
|
||||
<head>
|
||||
<title><?=$this->e($title)?></title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<?=$this->section('content')?>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
~~~
|
||||
|
||||
## Stacked layouts
|
||||
|
||||
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:
|
||||
|
||||
### The main site layout
|
||||
|
||||
<div class="filename">template.php</div>
|
||||
~~~ php
|
||||
<html>
|
||||
<head>
|
||||
<title><?=$this->e($title)?></title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<?=$this->section('content')?>
|
||||
|
||||
</body>
|
||||
</html>
|
||||
~~~
|
||||
|
||||
### The blog layout
|
||||
|
||||
<div class="filename">blog.php</div>
|
||||
~~~ php
|
||||
<?php $this->layout('template') ?>
|
||||
|
||||
<h1>The Blog</h1>
|
||||
|
||||
<section>
|
||||
<article>
|
||||
<?=$this->section('content')?>
|
||||
</article>
|
||||
<aside>
|
||||
<?=$this->insert('blog/sidebar')?>
|
||||
</aside>
|
||||
</section>
|
||||
~~~
|
||||
|
||||
### A blog article
|
||||
|
||||
<div class="filename">blog-article.php</div>
|
||||
~~~ php
|
||||
<?php $this->layout('blog', ['title' => $article->title]) ?>
|
||||
|
||||
<h2><?=$this->e($article->title)?></h2>
|
||||
<article>
|
||||
<?=$this->e($article->content)?>
|
||||
</article>
|
||||
~~~
|
||||
+44
@@ -0,0 +1,44 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/nesting/
|
||||
title: Nesting
|
||||
---
|
||||
|
||||
Nesting
|
||||
=======
|
||||
|
||||
Including another template into the current template is done using the `insert()` function:
|
||||
|
||||
~~~ php
|
||||
<?php $this->insert('partials/header') ?>
|
||||
|
||||
<p>Your content.</p>
|
||||
|
||||
<?php $this->insert('partials/footer') ?>
|
||||
~~~
|
||||
|
||||
The `insert()` function also works with [folders](/engine/folders/):
|
||||
|
||||
~~~ php
|
||||
<?php $this->insert('partials::header') ?>
|
||||
~~~
|
||||
|
||||
## Alternative syntax
|
||||
|
||||
The `insert()` function automatically outputs the rendered template. If you prefer to manually output the response, use the `fetch()` function instead:
|
||||
|
||||
~~~ php
|
||||
<?=$this->fetch('partials/header')?>
|
||||
~~~
|
||||
|
||||
## Assign data
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<?php $this->insert('partials/header', ['name' => 'Jonathan']) ?>
|
||||
|
||||
<p>Your content.</p>
|
||||
|
||||
<?php $this->insert('partials/footer') ?>
|
||||
~~~
|
||||
+80
@@ -0,0 +1,80 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/sections/
|
||||
title: Sections
|
||||
---
|
||||
|
||||
Sections
|
||||
========
|
||||
|
||||
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](/templates/layouts/) template.
|
||||
|
||||
## Creating sections
|
||||
|
||||
You define the name of the section with the `start()` function. To end a section call the `stop()` function.
|
||||
|
||||
~~~ php
|
||||
<?php $this->start('welcome') ?>
|
||||
|
||||
<h1>Welcome!</h1>
|
||||
<p>Hello <?=$this->e($name)?></p>
|
||||
|
||||
<?php $this->stop() ?>
|
||||
~~~
|
||||
|
||||
## Stacking section content
|
||||
|
||||
By default, when you render a section its content will overwrite any existing content for that section. However, it's possible to append (or stack) the content instead using the `push()` method. This can be useful for specifying any JavaScript libraries required by your child views.
|
||||
|
||||
~~~ php
|
||||
<?php $this->push('scripts') ?>
|
||||
<script src="example.js"></script>
|
||||
<?php $this->end() ?>
|
||||
~~~
|
||||
|
||||
<p class="message-notice">The <code>end()</code> function is simply an alias of <code>stop()</code>. These functions can be used interchangeably.</p>
|
||||
|
||||
## Accessing section content
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<?=$this->section('welcome')?>
|
||||
~~~
|
||||
|
||||
<p class="message-notice">Prior to Plates 3.0, accessing template content was done using either the <code>content()</code> or <code>child()</code> functions. For consistency with sections, this is no longer possible.</p>
|
||||
|
||||
## Default section content
|
||||
|
||||
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:
|
||||
|
||||
### Defining it inline
|
||||
|
||||
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 `content()` function.
|
||||
|
||||
~~~ php
|
||||
<div id="sidebar">
|
||||
<?=$this->section('sidebar', $this->fetch('default-sidebar')?>
|
||||
</div>
|
||||
~~~
|
||||
|
||||
### Use an if statement
|
||||
|
||||
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.
|
||||
|
||||
~~~ php
|
||||
<div id="sidebar">
|
||||
<?php if ($this->section('sidebar')): ?>
|
||||
<?=$this->section('sidebar')?>
|
||||
<?php else: ?>
|
||||
<ul>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
<li><a href="/link">Example Link</a></li>
|
||||
</ul>
|
||||
<?php endif ?>
|
||||
</div>
|
||||
~~~
|
||||
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
---
|
||||
layout: default
|
||||
permalink: templates/syntax/
|
||||
title: Syntax
|
||||
---
|
||||
|
||||
Syntax
|
||||
======
|
||||
|
||||
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.
|
||||
|
||||
## Guidelines
|
||||
|
||||
- Always use HTML with inline PHP. Never use blocks of PHP.
|
||||
- Always escape potentially dangerous variables prior to outputting using the built-in escape functions. More on escaping [here](/templates/escaping/).
|
||||
- Always use the short echo syntax (`<?=`) when outputting variables. For all other inline PHP code, use full the `<?php` tag. Do not use [short tags](http://us3.php.net/manual/en/ini.core.php#ini.short-open-tag).
|
||||
- Always use the [alternative syntax for control structures](http://php.net/manual/en/control-structures.alternative-syntax.php), which are designed to make templates more legible.
|
||||
- Never use PHP curly brackets.
|
||||
- Only ever have one statement in each PHP tag.
|
||||
- Avoid using semicolons. They are not needed when there is only one statement per PHP tag.
|
||||
- Never use the `use` operator. Templates should not be interacting with classes in this way.
|
||||
- Never use the `for`, `while` or `switch` control structures. Instead use `if` and `foreach`.
|
||||
- Avoid variable assignment.
|
||||
|
||||
## Syntax example
|
||||
|
||||
Here is an example of a template that complies with the above syntax rules.
|
||||
|
||||
~~~ php
|
||||
<?php $this->layout('template', ['title' => 'User Profile']) ?>
|
||||
|
||||
<h1>Welcome!</h1>
|
||||
<p>Hello <?=$this->e($name)?></p>
|
||||
|
||||
<h2>Friends</h2>
|
||||
<ul>
|
||||
<?php foreach($friends as $friend): ?>
|
||||
<li>
|
||||
<a href="/profile/<?=$this->e($friend->id)?>">
|
||||
<?=$this->e($friend->name)?>
|
||||
</a>
|
||||
</li>
|
||||
<?php endforeach ?>
|
||||
</ul>
|
||||
|
||||
<?php if ($invitations): ?>
|
||||
<h2>Invitations</h2>
|
||||
<p>You have some friend invites!</p>
|
||||
<?php endif ?>
|
||||
~~~
|
||||
Reference in New Issue
Block a user