Document @chunk and global placeholders available in field templates

Author: Mark-H

en/02_ContentBlocks/v1.x/00_Layouts.md

@@ -2,6 +2,8 @@ In ContentBlocks you can use _Layouts_ to easily manage multi column content. Ea
 
 During installation you get the opportunity to install some basic Foundation and Bootstrap based layouts to get started quickly.
 
+[TOC]
+
 ## Managing Layouts
 
  To manage Layouts, find the Content Blocks component under the Extras menu and move to the Layouts tab.

en/02_ContentBlocks/v1.x/01_Fields.md

@@ -2,6 +2,10 @@ Fields are implementation of an [Input Type](Input_Types) (such as _heading_ or
 
 To give a simple example, you may define "Note" and "Warning" fields so editors can add callout blocks into the content. These fields would both be a _textarea_ or _richtext_ input type, but because their template is different, they provide vastly different use cases and visual styles in the front-end.
 
+[TOC]
+
+## Managing Fields
+
 To manage fields, head over to Components and find the Content Blocks menu item. On the Fields tab, you can click _Add Field_, or right click a field and choose _Edit Field_ to open the field window. You'll find a number of tabs, which we'll go over in detail below, to help you manage your ContentBlocks fields.
 
 - General: used for managing the basic field information.

en/02_ContentBlocks/v1.x/01_Fields/Templates.md

@@ -0,0 +1,36 @@
+Field templates can be found by editing a [field in the ContentBlocks component](../Fields) and opening the Properties tab.
+
+## Placeholders
+
+Templates use the standard MODX parser, and have access to a number of placeholders in the form of `[[+KEY]]`. Which placeholders exactly depend on the [input type](../Input_Types).
+
+All field templates have access to a set of shared placeholders:
+
+- `[[+layout_id]]`, the ID of the parent layout the field is inserted in.
+- `[[+layout_column]]`, the string name of the column the field is inserted in.
+- `[[+idx]]`, an incrementing index for the fields inside the current column.
+- `[[+unique_idx]]`, a guaranteed to be unique incrementing index. This index number is incremented for each field or layout that is processed, nested layouts included, meaning the order is dependant on the exact page structure. You can **not** rely on two fields side-by-side being one index apart.
+- `[[+layout_idx]]`, an incrementing index for the position of the layout on the page.
+
+## Using @CHUNK
+
+If you'd like to use static elements, you can use chunks. The best way to do so is by using the `@CHUNK` syntax, which will pass all available placeholders into your chunk automatically.
+
+**Important to note: chunks are processed when rendering the page, rather than when saving it.** This means that using chunks in ContentBlocks comes at an extra performance penalty for the first (uncached) front-end request for a page.
+
+For example, define your template like this:
+
+```html
+@CHUNK NameOfYourChunk
+```
+
+That will be parsed by ContentBlocks into a full chunk tag, like this:
+
+```
+[[$NameOfYourChunk?
+    &value=`Some Value`
+    &layout_id=`5`
+    &layout_column=`main`
+    ...
+]]
+```

en/02_ContentBlocks/v1.x/02_Templates.md

@@ -4,6 +4,7 @@ Templates are available as of ContentBlocks v1.1. With Templates you can define
 
 The screenshots on this page were taken on Revolution 2.3, but this of course also works on 2.2.
 
+[TOC]
 
 ## Creating a Template
 

en/02_ContentBlocks/v1.x/03_Default_Templates.md

@@ -5,6 +5,7 @@ If you haven't worked with Templates before, be sure to [read more about Templat
 
 To manage your default templates, go to _Extras_ (or _Components_ pre-2.3) in the top navigation and choose ContentBlocks in the drop down. Open the Defaults tab.
 
+[TOC]
 
 ## Rules
 

en/02_ContentBlocks/v1.x/08_Parsing_Templates.md

@@ -4,6 +4,8 @@ title: Parsing & Templates
 
 ContentBlocks provides a revolutionary way of managing content. With this new way of doing things, there are also a few things to keep in mind when developing websites - in particular related to the way your page will be parsed and what is and what isn't possible. This document will walk you through a few of these limitations and best practices.
 
+[TOC]
+
 ## When & Where
 
 When you're using ContentBlocks, the layouts and fields you used are parsed **when the resource is saved**. This was done to make integration into your templates as easy as possible (by simply using `[[*content]]` in your template), as well as to prevent parsing the resource from slowing down the front-end of the website. As many [input types](Input_Types) offer very granular templateing, it is not uncommon for large or complex resources to take 0,5-2 seconds to fully parse, and you don't want that delay in front of your users.

en/02_ContentBlocks/v1.x/11_Internationalization.md

@@ -3,16 +3,20 @@ ContentBlocks is available in English (default), German, French, Dutch, Polish,
 
 The data you define through the component (fields, layouts and templates) also supports translations since v1.1. This allows you to present different names and descriptions for your users depending on their manager language. We support lexicons on field, layout and template names and descriptions, as well as field and layout settings and properties on select input types (chunk, snippet and chunk selector).
 
+[TOC]
+
 ## The Lexicon Files
 
 To load the lexicon, you will need to create a namespace and add a "lexicon" directory inside the namespace its core path.
 
 In there, you would have a directory for each language (`en`, `fr`, `de`, etc) and a file in each of those (e.g. `default.inc.php`). Within the file, you would add the lexicon entries to a `$_lang` variable. An example of a lexicon file is shown below.
-```` PHP
+
+````PHP
 <?php
 $_lang['my_richtext_field'] = 'Rich Text';
 $_lang['my_class'] = 'foobar';
 ````
+
 The entries (`my_richtext_field` and `my_class` in the example above) need to match the text you want to replace. This can be one of the following:
 
 - Field names (both for display in the content canvas, as well as the "Add Content" modal)
@@ -22,7 +26,7 @@ The entries (`my_richtext_field` and `my_class` in the example above) need to ma
 - Field and Layout Settings name (for modal and exposed settings)
 - Field and Layout Setting Options display values (for modal and exposed settings)
 
-For example, if you named a field "Headline", your lexicon entry would be `$_lang['Headline'] = 'Headline translation';
+For example, if you named a field "Headline", your lexicon entry would be `$_lang['Headline'] = 'Headline translation';`
 
 ## Loading the Lexicon Topic
 

en/02_ContentBlocks/v1.x/12_Permissions.md

@@ -1,5 +1,9 @@
 As of ContentBlocks 1.5, you have fine grained control over who can perform certain actions in the ContentBlocks Component. This uses the Access Control Lists features of MODX, that allows you to assign sets of permissions to a user group.
 
+[TOC]
+
+## Introduction
+
 During installation a Policy Template with the name `ContentBlocksTemplate` is created. This contains all the permissions for ContentBlocks, 35 at latest count, which you can add to Access Policies through that template. The full list can be seen in your manager, along with a brief description of each, by browsing to _System_ > _Access Control Lists_ > _Policy Templates_ > _ContentBlocksTemplate_.
 
 There are permissions that control access to the entire component (`contentblocks_component`) and it gets more granular from there on. With the `contentblocks_fields`, `contentblocks_layouts`, `contentblocks_templates`, `contentblocks_categories` and `contentblocks_defaults` permissions you can remove the specific tabs in one go.

en/02_ContentBlocks/v1.x/13_Custom_Resources.md

@@ -4,10 +4,12 @@ title: Custom Resources
 
 As of ContentBlocks 1.1 it is possible to use it on a variety of custom resource types.
 
-Once we have independently confirmed that third party custom resources work as expected with ContentBlocks, we will include it in the `contentblocks.accepted_resource_types` system setting so it is enabled by default. It is possible to manually add class keys to this setting if you want to test it with a resource type that we have not yet confirmed, or disable using ContentBlocks on certain resource types.
+[TOC]
 
 ## Supported Custom Resource Types
 
+Once we have independently confirmed that third party custom resources work as expected with ContentBlocks, we will include it in the `contentblocks.accepted_resource_types` system setting so it is enabled by default. It is possible to manually add class keys to this setting if you want to test it with a resource type that we have not yet confirmed, or disable using ContentBlocks on certain resource types.
+
 The following Extras are known to work with ContentBlocks and enabled by default as of 1.1.0:
 
 - MoreGallery