Improve templating content

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,23 +51,25 @@ 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') }}
@@ -70,14 +81,14 @@ Filters can be applied in succession. Filters are applied from left to right, wi
 {{ '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.