Merge branch '1.2' into develop

Author: bennothommo

database/model.md

@@ -736,7 +736,7 @@ public function addHasOneThroughRelation(string $name, array $config)
 public function addHasManyThroughRelation(string $name, array $config)
 ```
 
-It is strongly suggested to use the above methods to add relations when extending a model since they will merge the existing relations and make sure the relation is valid and does not already exit.
+It is strongly suggested to use the above methods to add relations when extending a model since they will merge the existing relations and make sure the relation is valid and does not already exist.
 
 Example usage:
 

markup/functions/form.md

@@ -110,6 +110,34 @@ The above example would output as the following:
 </form>
 ```
 
+## form_token()
+
+Outputs a `_token` hidden fields for CSRF protection.
+
+```twig
+{{ form_token() }}
+```
+
+The above example would output as the following:
+
+```html
+<input name="_token" type="hidden" value="...">
+```
+
+## form_submit()
+
+Outputs an `input` element of type `submit`. This tag is generally available to provide consistency in usage.
+
+```twig
+{{ form_submit() }}
+```
+
+The above example would output as the following:
+
+```html
+<input type="submit">
+```
+
 ## Passing attributes to the generated element
 
 You can pass additional attributes to the `Form::open()` method by passing an array of attribute names and values to be rendered on the final generated `<form>` element.

markup/templating/templating.md

@@ -1,38 +1,47 @@
+---
+title: "Markup: Templating"
+description: "Introduction to the markup syntax used in Winter CMS templates."
+---
+
 # Templating
 
-Winter extends the [Twig template language](https://twig.symfony.com/doc/3.x/) with a number of functions, tags, filters and variables. These extensions allow you to use the CMS features and access the page environment information inside your templates.
+Winter uses the [Twig template language](https://twig.symfony.com/doc/3.x/) to provide markup for theme templates, such as those used for layouts, partials and individual pages. Winter also extends Twig with a number of functions, tags, filters and variables to allow you to use the CMS features and access the page environment information inside your templates.
+
+It is recommended that you review the [Twig documentation](https://twig.symfony.com/doc/3.x/) to understand the basics of using Twig. The Markup documentation on Winter CMS will mainly cover the additional Twig functionality and extensions that Winter provides.
 
 ## Variables
 
-Template variables are printed on the page using *double curly brackets*.
+Template variables are printed on the page using the double curly bracket (`{{ }}`) format.
 
 ```twig
 {{ variable }}
 ```
 
-Variables can also represent *expressions*.
+You may also use expressions inside double curly brackets for conditional output.
 
 ```twig
 {{ isAjax ? 'Yes' : 'No' }}
 ```
 
-Variables can be concatenated with the `~` character.
+If you wish to concatenate the output, you may do so with the tilde (`~`) character.
 
 ```twig
-{{ 'Your name: ' ~ name }}
+{{ 'Your name: ' ~ first_name ~ ' ' ~ last_name }}
 ```
 
-Winter provides global variables under the `this` variable, as listed under the **Variables** section.
+If you use a variable that does not exist, by default, a `null` value is returned, which results in no output.
+
+Winter provides "global" variables under the `this` variable, as listed under the [Variables section](../this/page.md).
 
 ## Tags
 
-Tags are a unique feature to Twig and are wrapped with `{% %}` characters.
+In Twig, tags are used for control and functionality that (generally) are not output to the page. Tags are wrapped with `{% %}` characters.
 
 ```twig
 {% tag %}
 ```
 
-Tags provide a more fluent way to describe template logic.
+Tags provide a more fluent way to describe template logic and implement conditions or flow.
 
 ```twig
 {% if stormCloudComing %}
@@ -42,42 +51,44 @@ Tags provide a more fluent way to describe template logic.
 {% endif %}
 ```
 
-The `{% set %}` tag can be used to set variables inside the template.
+For example, the `{% set %}` tag can be used to set variables inside the template, which can then be used later on in the same template.
 
 ```twig
 {% set activePage = 'blog' %}
+
+My active page: {{ activePage }}
 ```
 
-Tags can take on many different syntaxes and are listed under the **Tags** section.
+Tags can take on many different signatures and are listed under the [Tags section](../tags/page.md).
 
 ## Filters
 
-Filters act as modifiers to variables for a single instance and are applied using a *pipe symbol* followed by the filter name.
+Filters act as modifiers to variables within the same variable tag, and are applied using a pipe symbol (`|`) followed by the filter name.
 
 ```twig
 {{ 'string' | filter }}
 ```
 
-Filters can take arguments like a function.
+Filters can take arguments like a function in PHP.
 
 ```twig
 {{ price | currency('USD') }}
 ```
 
-Filters can be applied in succession.
+Filters can be applied in succession. Filters are applied from left to right, with the result of the first filter being passed as the input to the second filter, and so on.
 
 ```twig
-{{ 'Winter Glory' | upper | replace({'Winter': 'Morning'}) }}
+{{ 'Winter Rain' | upper | replace({'Rain': 'Storm'}) }}
 ```
 
-Filters are listed under the **Filters** section.
+Filters are listed under the [Filters section](../filters/app.md).
 
 ## Functions
 
-Functions allow logic to be executed and the return result acts as a variable.
+Functions can be used within variable tags to display the output of logic that is defined by Winter, the theme or a plugin.
 
 ```twig
-{{ function() }}
+{{ theFunction() }}
 ```
 
 Functions can take arguments.
@@ -86,11 +97,11 @@ Functions can take arguments.
 {{ dump(variable) }}
 ```
 
-Functions are listed under the **Functions** section.
+Functions are listed under the [Functions section](../functions/str.md).
 
-## Access logic
+## Access logic and priority
 
-The most important thing to learn about Twig is how it accesses the PHP layer. For convenience sake `{{ foo.bar }}` does the following checks on a PHP object:
+The most important thing to learn about Twig is how it accesses the PHP layer and how it prioritises the location of where a particular object or variable is read from. For example, using `{{ foo.bar }}` in your template to get the `bar` parameter of the `foo` object is determined in the following order:
 
 1. Check if `foo` is an array and `bar` a valid element.
 1. If not, and if `foo` is an object, check that `bar` is a valid property.
@@ -107,3 +118,7 @@ Tag | Equivalent
 ------------- | -------------
 `{% extend %}` | Use [Layouts](../../docs/cms/layouts) or `{% placeholder %}`
 `{% include %}` | Use `{% partial %}` or `{% content %}`
+
+## Custom Twig filters and functions
+
+Custom Twig filters and functions can be registered with the `registerMarkupTags` method of the plugin registration class. For detailed documentation see [Extending Twig](../../docs/plugin/registration#extending-twig).