Add docs to master branch (from gh-pages).

thephpleague · Dec 27, 2016 · 832c486 · 832c486
1 parent 30e0671
commit 832c486
Show file tree

Hide file tree

Showing 29 changed files with 1,343 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -1,3 +1,4 @@
 build
 composer.lock
-vendor
+vendor
+docs/_site
diff --git a/docs/CNAME b/docs/CNAME
@@ -0,0 +1 @@
+platesphp.com
diff --git a/docs/_data/images.yml b/docs/_data/images.yml
@@ -0,0 +1,8 @@
+# Path to project specific favicon.ico, leave blank to use default
+favicon: /favicon.ico
+
+# Path to project specific apple-touch-icon-precomposed.png, leave blank to use default
+apple_touch: /apple-touch-icon-precomposed.png
+
+# Path to project logo
+logo: /logo.png
diff --git a/docs/_data/menu.yml b/docs/_data/menu.yml
@@ -0,0 +1,24 @@
+Getting Started:
+    Introduction: '/'
+    Simple example: '/simple-example/'
+    Installation: '/installation/'
+    Changelog: '/changelog/'
+The Engine:
+    Overview: '/engine/'
+    File extensions: '/engine/file-extensions/'
+    Folders: '/engine/folders/'
+    Functions: '/engine/functions/'
+    Extensions: '/engine/extensions/'
+Templates:
+    Overview: '/templates/'
+    Data: '/templates/data/'
+    Functions: '/templates/functions/'
+    Nesting: '/templates/nesting/'
+    Layouts: '/templates/layouts/'
+    Sections: '/templates/sections/'
+    Inheritance: '/templates/inheritance/'
+    Escaping: '/templates/escaping/'
+    Syntax: '/templates/syntax/'
+Extensions:
+    Asset: '/extensions/asset/'
+    URI: '/extensions/uri/'
diff --git a/docs/_data/project.yml b/docs/_data/project.yml
@@ -0,0 +1,4 @@
+title: Plates
+tagline: Native PHP Templates
+description: 'Plates is a Twig inspired, native PHP template system that brings modern template language functionality to native PHP templates.'
+google_analytics_tracking_id: UA-46050814-2
diff --git a/docs/_layouts/default.html b/docs/_layouts/default.html
@@ -0,0 +1,102 @@
+<!DOCTYPE html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    {% if page.url == '/' %}
+        <title>{{ site.data.project.title }} - {{ site.data.project.tagline }}</title>
+    {% else %}
+        <title>{{ page.title }} - {{ site.data.project.title }}</title>
+    {% endif %}
+    {% if site.data.project.description %}
+        <meta name="description" content="{{ site.data.project.description }}">
+    {% endif %}
+    {% if site.github.url %}
+        <base href="{{ site.github.url }}">
+    {% endif %}
+    {% if site.data.images.favicon %}
+        <link rel="icon" type="image/x-icon" href="{{ site.data.images.favicon }}" />
+    {% else %}
+        <link rel="icon" type="image/x-icon" href="http://theme.thephpleague.com/img/favicon.ico" />
+    {% endif %}
+    {% if site.data.images.apple_touch %}
+        <link rel="apple-touch-icon-precomposed" href="{{ site.data.images.apple_touch }}">
+    {% else %}
+        <link rel="apple-touch-icon-precomposed" href="http://theme.thephpleague.com/img/apple-touch-icon-precomposed.png">
+    {% endif %}
+    <link rel="stylesheet" href="http://theme.thephpleague.com/css/all.css">
+</head>
+<body>
+
+<section class="all_packages">
+    <a href="http://thephpleague.com/">
+        <img src="http://theme.thephpleague.com/img/loep_logo.png" width="195" height="200" alt="The League of Extraordinary Packages">
+    </a>
+    <h2>Our Packages:</h2>
+    <ul>
+        <!-- Loaded via JavaScript -->
+    </ul>
+</section>
+
+<header>
+    <a class="logo" href="/">
+        {% if site.data.images.logo %}
+            <span class="icon">
+                <img src="{{ site.data.images.logo }}" width="50" height="40" alt="{{ site.data.project.title }} - {{ site.data.project.tagline }}">
+            </span>
+        {% endif %}
+        <span class="name">{{ site.data.project.title }}</span>
+        <span class="tagline">{{ site.data.project.tagline }}</span>
+    </a>
+    <a href="http://thephpleague.com/" class="league">
+        Presented by The League of Extraordinary Packages
+    </a>
+</header>
+
+<input type="checkbox" id="menu">
+<label for="menu" onclick>
+    <div class="closed">&#9776; Menu</div>
+    <div class="open">&#9776; Hide Menu</div>
+</label>
+
+<main>
+    <menu>
+        {% for section in site.data.menu %}
+            <h2>{{ section[0] }}</h2>
+            <ul>
+                {% for link in section[1] %}
+                    <li {% if page.url == link[1] %}class="selected"{% endif %}>
+                        <a href="{{ link[1] }}">{{ link[0] }}</a>
+                    </li>
+                {% endfor %}
+            </ul>
+        {% endfor %}
+    </menu>
+    <article>
+        {{ content }}
+    </article>
+</main>
+
+<footer>
+    <span>&copy; Copyright <a href="http://thephpleague.com">The League of Extraordinary Packages</a>.</span>
+    <span>Site design by <a href="http://reinink.ca">Jonathan Reinink</a>.</span>
+</footer>
+
+<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
+<script src="http://theme.thephpleague.com/js/scripts.js"></script>
+<script src="http://theme.thephpleague.com/js/prism.js"></script>
+
+{% if site.data.project.google_analytics_tracking_id %}
+    <script>
+        (function(b,o,i,l,e,r){b.GoogleAnalyticsObject=l;b[l]||(b[l]=
+        function(){(b[l].q=b[l].q||[]).push(arguments)});b[l].l=+new Date;
+        e=o.createElement(i);r=o.getElementsByTagName(i)[0];
+        e.src='//www.google-analytics.com/analytics.js';
+        r.parentNode.insertBefore(e,r)}(window,document,'script','ga'));
+        ga('create','{{  site.data.project.google_analytics_tracking_id }}');ga('send','pageview');
+    </script>
+{% endif %}
+
+</body>
+</html>
diff --git a/docs/apple-touch-icon-precomposed.png b/docs/apple-touch-icon-precomposed.png
diff --git a/docs/changelog.md b/docs/changelog.md
@@ -0,0 +1,77 @@
+---
+layout: default
+permalink: changelog/
+title: Changelog
+---
+
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+## Version 3.1.1 - 2015-07-09
+
+### Changed
+
+- Fix bug related to output buffering and exceptions (#78)
+- Improvements to escaping (#56)
+- Various CI and packaging improvements
+
+## Version 3.1.0 - 2014-10-21
+
+### Added
+
+- Added batch functionality to the escaping functions. See [functions](/templates/functions/#batch-function-calls) for more information.
+
+## Version 3.0.3 - 2014-10-20
+
+### Added
+
+- Added ability to define the default content of a section. See [sections](/templates/sections/#default-section-content) for more information.
+
+## Version 3.0.2 - 2014-10-01
+
+### Changed
+
+- Fixed bug with fallback folders, where the file extension wasn't being applied.
+
+## Version 3.0.0 - 2014-09-27
+
+### Added
+
+- Added ability to share data across templates.
+- Added ability to preassign data to specific templates.
+- Added ability to create one-off template [functions](/engine/functions/), without using an extension.
+- Added new folder "fall backs", where missing folder templates will fall back to the default folder.
+- Added new `render()` method to `Engine` class, improving the use of the `Engine` as the primary API.
+
+### Changed
+
+- Templates variables are now accessed without the `$this` pseudo-variable.
+- Total overhaul to how extensions are registered. Replaced `getFunctions()` method with new `register()` method. See [extensions](/engine/extensions/) for more information.
+- Section content is no longer assigned to template variables. Use the the `section()` function instead.
+- Renamed section `end()` function to `stop()`. This fits more appropriately with the `start()` function.
+- Renamed `get()` function to `fetch()`.
+- Renamed `pathExists()` method in the `Engine` class to `exists()`.
+- Renamed `getTemplatePath()` method in the `Engine` class to `path()`.
+- Renamed `makeTemplate()` method in the `Engine` class to `make()`.
+
+### Removed
+
+- Removed the ability to assign template data directly to the `Template` class. For example:  `$this->name = 'Jonathan'`. This applies both within and outside of templates. Use the `data()` method instead. See [data](http://platesphp.com/templates/data/) for more information.
+- Removed `getEngine()` method from the `Template` class. There's no reason to need this anymore.
+- Removed `addFolders()` method from the `Engine()` class.
+- Removed `unloadExtension()` and `unloadExtensionFunction()` methods from the `Engine()` class.
+
+## Version 2.0.0 - 2014-03-31
+
+### Added
+
+- Added stacked layouts, allowing even further simplification and organization of templates.
+- Added new `unloadExtension()` and `unloadExtensionFunction()` methods to the `Engine()` class.
+- Added `getEngine()` method to the `Template` class.
+- Added `addFolders()` and `loadExtensions()` methods to the `Engine()` class.
+
+### Changed
+
+- Nested templates are now self-contained objects, with their own variables and layouts.
diff --git a/docs/engine/extensions.md b/docs/engine/extensions.md
@@ -0,0 +1,120 @@
+---
+layout: default
+permalink: engine/extensions/
+title: Extensions
+---
+
+Extensions
+==========
+
+Creating extensions couldn't be easier, and can really make Plates sing for your specific project. Start by creating a class that implements `\League\Plates\Extension\ExtensionInterface`. Next, register your template [functions](/engine/functions/) within a `register()` method.
+
+## Simple extensions example
+
+~~~ php
+use League\Plates\Engine;
+use League\Plates\Extension\ExtensionInterface;
+
+class ChangeCase implements ExtensionInterface
+{
+    public function register(Engine $engine)
+    {
+        $engine->registerFunction('uppercase', [$this, 'uppercaseString']);
+        $engine->registerFunction('lowercase', [$this, 'lowercaseString']);
+    }
+
+    public function uppercaseString($var)
+    {
+        return strtoupper($var);
+    }
+
+    public function lowercaseString($var)
+    {
+        return strtolower($var);
+    }
+}
+~~~
+
+To use this extension in your template, simply call your new functions:
+
+~~~ php
+<p>Hello, <?=$this->e($this->uppercase($name))?></p>
+~~~
+
+They can also be used in a [batch](/templates/functions/#batch-function-calls) compatible function:
+
+~~~ php
+<h1>Hello <?=$this->e($name, 'uppercase')</h1>
+~~~
+
+## Single method extensions
+
+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.
+
+~~~ php
+use League\Plates\Engine;
+use League\Plates\Extension\ExtensionInterface;
+
+class ChangeCase implements ExtensionInterface
+{
+    public function register(Engine $engine)
+    {
+        $engine->registerFunction('case', [$this, 'getObject']);
+    }
+
+    public function getObject()
+    {
+        return $this;
+    }
+
+    public function upper($var)
+    {
+        return strtoupper($var);
+    }
+
+    public function lower($var)
+    {
+        return strtolower($var);
+    }
+}
+~~~
+
+To use this extension in your template, first call the primary function, then the secondary functions:
+
+~~~ php
+<p>Hello, <?=$this->e($this->case()->upper($name))?></p>
+~~~
+
+## Loading extensions
+
+To enable an extension, load it into the [engine](/engine/) object using the `loadExtension()` method.
+
+~~~ php
+$engine->loadExtension(new ChangeCase());
+~~~
+
+## Accessing the engine and template
+
+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.
+
+~~~ php
+use League\Plates\Engine;
+use League\Plates\Extension\ExtensionInterface;
+
+class MyExtension implements ExtensionInterface
+{
+    protected $engine;
+    public $template; // must be public
+
+    public function register(Engine $engine)
+    {
+        $this->engine = $engine;
+
+        // Access template data:
+        $data = $this->template->data();
+
+        // Register functions
+        // ...
+    }
+}
+~~~
diff --git a/docs/engine/file-extensions.md b/docs/engine/file-extensions.md
@@ -0,0 +1,36 @@
+---
+layout: default
+permalink: engine/file-extensions/
+title: File extensions
+---
+
+File extensions
+===============
+
+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.
+
+## Constructor method
+
+~~~ php
+// Create new engine and set the default file extension to ".tpl"
+$template = new League\Plates\Engine('/path/to/templates', 'tpl');
+~~~
+
+## Setter method
+
+~~~ php
+// Sets the default file extension to ".tpl" after engine instantiation
+$template->setFileExtension('tpl');
+~~~
+
+## Manually assign
+
+If you prefer to manually set the file extension, simply set the default file extension to `null`.
+
+~~~ php
+// Disable automatic file extensions
+$template->setFileExtension(null);
+
+// Render template
+echo $templates->render('home.php');
+~~~