Merge branch 'develop' into feature/forms_2.0_updates

Author: rhukster

config/site.yaml

@@ -26,5 +26,6 @@ redirects:
   '/advanced/forms': '/forms/forms'
   '/advanced/contact-form': '/forms/example-form'
   '/advanced/grav-lifecycle': '/plugins/grav-lifecycle'
+  '/hosting/(.*)': '/webservers-hosting/$1'
 
 

learn.dev/config/system.yaml

@@ -1,2 +1,9 @@
 cache:
   enabled: false
+
+assets:
+  css_pipeline: false
+  css_minify: true
+  css_rewrite: true
+  js_pipeline: false
+  js_minify: true

pages/01.basics/03.installation/docs.md

@@ -97,7 +97,7 @@ If any issues are discovered during the initial page load (or after a cache-flus
 
 Please consult the [Troubleshooting](../../troubleshooting) section for help regarding specific issues.
 
-! If you have issues with file permissions, please check the [Permissions Troubleshooting documentation](/troubleshooting/permissions).  Also you could look at the [Hosting Guides documentation](/hosting) that have specific instructions for various hosting environments
+! If you have issues with file permissions, please check the [Permissions Troubleshooting documentation](/troubleshooting/permissions).  Also you could look at the [Hosting Guides documentation](/webservers-hosting) that have specific instructions for various hosting environments
 
 ## Grav Updates
 

pages/01.basics/05.grav-configuration/docs.md

@@ -56,7 +56,7 @@ pages:
   twig_first: false                         # Process Twig before markdown when processing both on a page
   events:
     page: true                              # Enable page level events
-    twig: true                              # Enable twig level events
+    twig: true                              # Enable Twig level events
   markdown:
     extra: false                            # Enable support for Markdown Extra support (GFM by default)
     auto_line_breaks: false                 # Enable automatic line breaks
@@ -92,7 +92,7 @@ cache:
   gzip: false                               # GZip compress the page output
 
 twig:
-  cache: true                               # Set to true to enable twig caching
+  cache: true                               # Set to true to enable Twig caching
   debug: true                               # Enable Twig debug
   auto_reload: true                         # Refresh cache on changes
   autoescape: false                         # Autoescape Twig vars
@@ -214,11 +214,29 @@ User configuration is completely optional. You can override as little or as much
 
 You are also not limited to the `user/config/system.yaml` or the `user/config/site.yaml` files as described above. You can create any arbitrary `.yaml` configuration file in the `user/config` folder you wish and it will get picked up by Grav automatically.
 
-Paths to the configuration files will be used as a **namespace** for your configuration options.
+As an example if the new configuration file is named `user/config/data.yaml` and a yaml variable in this file is called count:
+
+```
+count: 39
+```
+
+The variable would be accessed in your Twig template by using the following syntax:
+
+```
+{{ config.data.count }}
+```
+
+It would also be accessible via PHP from any plugin with the code:
 
-As an example if the new configuration file is named data.yaml and a yaml variable in this file is called count, the variable would be accessed in your twig template by using the following syntax:
+```
+$count_var = Grav::instance()['config']->get('data.count');
+```
 
-    {{config.data.count}}
+! You can also provide a custom blueprint to enable your custom file to be editable in the admin plugin. Check out the relevant [recipe in the Admin Cookbook section](/cookbook/admin-recipes#add-a-custom-yaml-file).
+
+## Config Variable Namespacing
+
+Paths to the configuration files will be used as a **namespace** for your configuration options.
 
 Alternatively, you can put all the options into one file and use YAML structures to specify the hierarchy for your configuration options. This namespacing is built from a combination of the **path + filename + option name**.
 

pages/02.content/02.headers/docs.md

@@ -217,7 +217,7 @@ There are situations when you want to use Twig templating functionality in your
 twig_first: false
 ```
 
-If set to `true` Twig processing will occur before any Markdown processing. This can be particularly useful if your twig generates markdown that needs to be available in order to be processed by the Markdown compiler.  One thing to note, if have `cache_enable: false` **and** `twig_first: true` page caching is effectively disabled.
+If set to `true` Twig processing will occur before any Markdown processing. This can be particularly useful if your Twig generates markdown that needs to be available in order to be processed by the Markdown compiler.  One thing to note, if have `cache_enable: false` **and** `twig_first: true` page caching is effectively disabled.
 
 ### Markdown
 

pages/02.content/03.collections/docs.md

@@ -43,8 +43,8 @@ To tell Grav that a specific page should be a listing page and contain child-pag
 
 ### Summary of collection options
 
-| String                                    | Result                                                    |
-| :----------                               | :----------                                               |
+|                   String                  |                           Result                          |
+|-------------------------------------------|-----------------------------------------------------------|
 | '@root'                                   | Get the root children                                     |
 | '@root.children'                          | Get the root children (alternative)                       |
 | '@root.descendants'                       | Get the root and recurse through ALL children             |
@@ -55,13 +55,16 @@ To tell Grav that a specific page should be a listing page and contain child-pag
 | '@self.children'                          | Get the non-modular children                              |
 | '@self.descendants'                       | Recurse through all the non-modular children              |
 |                                           |                                                           |
-| '@page': '/fruit'                         | Get all the children of page `/fruit'                     |
+| '@page': '/fruit'                         | Get all the children of page `/fruit`                     |
 | '@page.children': '/fruit'                | Alternative to above                                      |
-| '@page.self': '/fruit'                    | Get a collection with only the page `/fruit'               |
-| '@page.descendants': '/fruit'             | Get and recurse through all the children of page '/fruit' |
+| '@page.self': '/fruit'                    | Get a collection with only the page `/fruit`              |
+| '@page.page': '/fruit'                    | Alternative to above                                      |
+| '@page.descendants': '/fruit'             | Get and recurse through all the children of page `/fruit` |
+| '@page.modular': '/fruit'                 | Get a collection of all modular subpages of `/fruit`      |
 |                                           |                                                           |
-| '@taxonomy.tag': photography              | taxonomy with tag='photography'                           |
-| '@taxonomy': {tag: birds, category: blog} | taxonomy with tag='birds' && category='blog'              |
+| '@taxonomy.tag': photography              | taxonomy with tag=`photography`                           |
+| '@taxonomy': {tag: birds, category: blog} | taxonomy with tag=`birds` && category=`blog`              |
+
 
 ! This document outlines the use of `@page`, `@taxonomy.category` etc, but a more YAML-safe alternative format is `page@`, `[email protected]`.  All the `@` commands can be written in either prefix or postfix format.
 
@@ -143,32 +146,32 @@ content:
 
 ## Page Collections
 
-##### @page - Collection of children of a specific page
+##### @page or @page.children - Collection of children of a specific page
 
 This collection takes a slug route of a page as an argument and will return all the **published non-modular** children of that page
 
 ```ruby
 content:
     items:
-      '@page': /blog
+      '@page': '/blog'
 ```
 
 alternatively:
 
 ```ruby
 content:
     items:
-      '@page.children': /blog
+      '@page.children': '/blog'
 ```
 
-##### @page.self - Collection of just the specific page
+##### @page.self or @page.page - Collection of just the specific page
 
 This collection takes a slug route of a page as an argument and will return collection containing that page (if it is **published and non-modular**)
 
 ```ruby
 content:
     items:
-      '@page.self': /blog
+      '@page.self': '/blog'
 ```
 
 ##### @page.descendants - Collection of children + all descendants of a specific page
@@ -178,9 +181,20 @@ This collection takes a slug route of a page as an argument and will return all
 ```ruby
 content:
     items:
-      '@page.descendants': /blog
+      '@page.descendants': '/blog'
 ```
 
+##### @page.modular - Collection of modular children of a specific page
+
+This collection takes a slug route of a page as an argument and will return all the **published modular** children of that page
+
+```ruby
+content:
+    items:
+      '@page.modular': '/blog'
+```
+
+
 ## Taxonomy Collections
 
 ```ruby

pages/02.content/11.multi-language/docs.md

@@ -192,7 +192,7 @@ This way Grav knows how to route your to the homepage if the active language is
 
 #### Language-Based Twig Templates
 
-By default, Grav uses the markdown filename to determine the Twig template to use to render.  This works with multi-language the same way.  For example, `default.fr.md` would look for a twig file called `default.html.twig` in the appropriate Twig template paths of the current theme and any plugins that register Twig template paths.  With multi-language, Grav also adds the current active language to the path structure.  What this means is that if you need to have a language-specific Twig file, you can just put those into a root level language folder.  For example if your current theme is using a template located at `templates/default.html.twig` you can create an `templates/fr/` folder, and put your French-specific Twig file in there: `templates/fr/default.html.twig`.
+By default, Grav uses the markdown filename to determine the Twig template to use to render.  This works with multi-language the same way.  For example, `default.fr.md` would look for a Twig file called `default.html.twig` in the appropriate Twig template paths of the current theme and any plugins that register Twig template paths.  With multi-language, Grav also adds the current active language to the path structure.  What this means is that if you need to have a language-specific Twig file, you can just put those into a root level language folder.  For example if your current theme is using a template located at `templates/default.html.twig` you can create an `templates/fr/` folder, and put your French-specific Twig file in there: `templates/fr/default.html.twig`.
 
 Another option which requires manual setup is to override the `template:` setting in the page headers. For example:
 

pages/02.content/12.content-types/docs.md

@@ -0,0 +1,72 @@
+---
+title: Content Types
+taxonomy:
+    category: docs
+---
+
+## Default Content Type
+
+As is typical with most web platforms, Grav's default content type is **HTML**. This means than when a user requests a route in their browser, for example: `/blog/new-macbook-pros-soon`, because there is no file extension Grav assumes you are requesting an HTML page.  If your page was defined by a page with filename of  `blog-item.md`, Grav in turn looks for a Twig template called `blog-item.html.twig`  to render the page.
+
+If the user requested the type explicitly via `/blog/new-macbook-pros-soon.html`, Grav would still look for that same `blog-item.html.twig` file.
+
+## Other Content Types
+
+Grav is a flexible platform however, and can actually serve up any content type you could wish for (`xml`, `rss`, `json`, `pdf`, etc.), you just have to provide a way to render it appropriately.
+
+If you were to request a route with a `.xml` extension, for example: `/blog.xml`,  instead of using the regular `blog.html.twig` template to render it,
+Grav look for a template called `blog.xml.twig`.  You would need to ensure that template output the appropriate XML structure.
+
+### Example with JSON files
+
+A particular common way to access files is via a `.json` extension.  This is allows data to be requested via JSON files that are easily processed by JavaScript.
+
+Say you wanted the **frontmatter** and **content** of a particular page in JSON format, and that page was defined in a file called `item.md`.  All you would need to do is to provide a Twig template called `item.json.html`.  You could put this in your theme's `templates/` folder, or if you were using a plugin to load custom templates, you could add it there.
+
+The contents of this `item.json.twig` file could look something like:
+
+```
+{% set payload = {frontmatter: page.header, content: page.content}  %}
+{{ payload|json_encode|raw }}
+```
+
+All this Twig file does is create an array with the page header as **frontmatter** and page **content**, then uses the Twig `json_encode` filter to encode it.
+
+When a user requests the url: `/blog/new-macbook-pros-soon.json` this new Twig file would be used and the output sent would be in the format:
+
+```
+{
+   "header":{
+      "title":"New Macbook Pros Arriving Soon",
+      "date": "14:23 08/01/2016",
+      "taxonomy":{
+         "category":[
+            "blog"
+         ],
+         "tag":[
+            "apple",
+            "mbpr",
+            "laptops"
+         ]
+      }
+   },
+   "content":"<p>this has an -&gt; arrow here and <strong>bold</strong> here</p>\n<blockquote>\n<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec ultricies tristique nulla et mattis. Phasellus id massa eget nisl congue blandit sit amet id ligula. Praesent et nulla eu augue tempus sagittis. Mauris faucibus nibh et nibh cursus in vestibulum sapien egestas. Curabitur ut lectus tortor. Sed ipsum eros, egestas ut eleifend non, elementum vitae eros.\n-- <cite> Ronald Wade</cite></p>\n</blockquote>\n<p>Mauris felis diam, pellentesque vel lacinia ac, dictum a nunc. Mauris mattis nunc sed mi sagittis et facilisis tortor volutpat. Etiam tincidunt urna mattis erat placerat placerat ac eu tellus.</p>\n<p>This is a new paragraph</p>\n<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec ultricies tristique nulla et mattis.</p>"
+}
+```
+
+This is valid JSON that can easily be parsed and processed by JavaScript.  Easy Peasy!
+
+## Custom Content Types
+
+In order to send the data with the appropriate content type, Grav needs to know the MIME type that the browser expects in order for it to render that content type.  Grav knows about most of the standard content types as defined in the `system/config/media.yaml` file.  If you wish to handle a content type that is not provided, you just need to add an entry to this file.
+
+For example, if you wish to be able to render iCal calendar events, you would need to add this media type to the `media.yaml`:
+
+```
+  ics:
+    type: iCal
+    thumb: media/thumb.png
+    mime: text/calendar
+```
+
+This defines the `.ics` file extension as an `iCal` file with mime type: `text/calendar`.  Then all you need to do is provide the appropriate `.ical.twig` template to render any file you request of this type.

pages/03.themes/01.theme-basics/docs.md

@@ -8,15 +8,15 @@ Themes in Grav are quite simple, and very flexible because they are built with t
 
 ## Content Pages & Twig Templates
 
-The first thing to understand is the direct relationship between **pages** in Grav and the **twig template files** that are provided in a theme.
+The first thing to understand is the direct relationship between **pages** in Grav and the **Twig template files** that are provided in a theme.
 
 Each page you create references a specific template file, either by the name of the page file, or by setting the template header variable for the page.  For simpler maintenance, we advise using the page name rather than overriding it with the header variable, whenever possible.
 
-Let us work through a simple example.  If you have [installed the **Grav Base** package](../../basics/installation) you will notice that in the `user/pages/01.home` folder, you have a file called `default.md` which contains the markdown-based content for the page.  The name of this file, i.e. `default` tells Grav that this page should be rendered with the twig template called `default.html.twig` which is located in the theme's `templates/` folder.
+Let us work through a simple example.  If you have [installed the **Grav Base** package](../../basics/installation) you will notice that in the `user/pages/01.home` folder, you have a file called `default.md` which contains the markdown-based content for the page.  The name of this file, i.e. `default` tells Grav that this page should be rendered with the Twig template called `default.html.twig` which is located in the theme's `templates/` folder.
 
 !! Page templates must be lowercase, like "default", "blog", etc.
 
-If you were to have a page file called `blog.md`, Grav would try to render it with the twig template: `<your_theme>/templates/blog.html.twig`.
+If you were to have a page file called `blog.md`, Grav would try to render it with the Twig template: `<your_theme>/templates/blog.html.twig`.
 
 !! The names of files in Grav do not appear on the frontend of Grav. Only the folder names do. Don't worry if all of your blog posts have the same file name. This is normal.
 
@@ -114,13 +114,13 @@ You can then use the provided **plugins methods** which are covered in the [next
 
 ### Templates
 
-There are **no set rules** regarding the structure of a Grav theme except that there must be appropriate twig templates provided in the `templates/` folder for each of the page types you use in your content.
+There are **no set rules** regarding the structure of a Grav theme except that there must be appropriate Twig templates provided in the `templates/` folder for each of the page types you use in your content.
 
-!! Because of this tight coupling between page content and twig templates in a theme, it often makes sense to develop themes in conjunction with the content they are intended to be used with.  A good way to create _general_ themes is to support the template types used by the Skeleton packages that are available on our [downloads page](http://getgrav.org/downloads). For example, support: **default**, **blog**, **error**, **item**, and **modular**.
+!! Because of this tight coupling between page content and Twig templates in a theme, it often makes sense to develop themes in conjunction with the content they are intended to be used with.  A good way to create _general_ themes is to support the template types used by the Skeleton packages that are available on our [downloads page](http://getgrav.org/downloads). For example, support: **default**, **blog**, **error**, **item**, and **modular**.
 
 Generally speaking, the root of the `templates/` folder should be used to house the primary templates that are supported, then create a sub-folder called `partials/` to contain parts, or smaller template _chunks_.
 
-If you want to support **modular** templates in your theme, you should also create a sub-folder of templates called `modular/` and store your modular twig template files in there.
+If you want to support **modular** templates in your theme, you should also create a sub-folder of templates called `modular/` and store your modular Twig template files in there.
 
 The story for supporting **forms** is the same. Create another sub-folder called `forms/` and store any custom form templates in it.