Merge branch 'b20'

Author: jasonvarga

content/collections/fieldtypes/redactor.md

@@ -5,12 +5,11 @@ image: 22318543-6610-45b9-b21b-d1bed3b2afe7
 options:
   -
     name: settings
-    type: array
+    type: string
     description: >
-      An array of settings to be passed into
-      the Redactor plugin. This should be a
-      YAML version of the Javascript object
-      you would use to initialize Redactor.
+      The _name_ of the Redactor setting configuration you want to use.
+      If you leave this blank, or specify a name that doesn't exist,
+      Statamic will use the first set of settings in the list.
 id: 25d8be49-2300-42ac-90e4-92df42fc2906
 ---
 ## Data Structure {#data-structure}
@@ -22,14 +21,32 @@ quote: |
   <blockquote>I signed up for Second Life about a year ago. Back then, my life was so great that I literally wanted a second one. Absolutely everything was the same... except I could fly.</blockquote><p>– Dwight Schrute</p>  
 ```
 
-This is fine, but keep it in mind if you're using it for your `content` field set to "markdown". Statamic parse the `content` as Markdown and any unintended text indentation will be converted to code blocks.
-
-[redactor-docs]: https://imperavi.com/assets/pdf/redactor-documentation-10.pdf
+This is fine, but keep it in mind if you're using it for your `content` field and are using a markdown file.
+Statamic automatically parses the `content` field as Markdown within `md` files.
 
 
 ## Redactor.js Configuration {#configuration}
 
-You are able to customize all of the Redactor options. You can [view the full list of settings in the Redactor documentation][redactor-docs]
+You are able to set any number of predefined Redactor setting configurations. We give you two out of the box, but of
+course you are free to modify those and add more.
+
+``` .language-yaml
+-
+  name: Standard
+  settings:
+    buttons: [formatting, bold, italic, unorderedlist, orderedlist, html]
+-
+  name: Basic
+  settings:
+    buttons: [bold, italic]
+```
+
+Each item has a name, which is what you will see when configuring your fieldtype, and the settings themselves.
+
+You can find these Redactor settings in `Configure > Settings > System` or within `site/settings/system.yaml`.
+
+The `settings` value should be a YAML representation of the options object that will get passed into the Redactor jQuery
+plugin. You are able to customize all of the Redactor options. You can [view the full list of settings in the Redactor documentation][redactor-docs].
 
 Any settings and options available to the plugin can be set here. For example, if the docs say to use the following configuration object:
 
@@ -43,12 +60,16 @@ $('textarea').redactor({
 You would translate to YAML like so:
 
 ``` .language-yaml
-settings:
-  formatting:
-    - p
-    - blockquote
-    - h2
-  minHeight: 300
+-
+  name: My Redactor Settings
+  settings:
+    formatting:
+      - p
+      - blockquote
+      - h2
+    minHeight: 300
 ```
 
 *Note: Function type options (eg. callbacks) are not supported.*
+
+[redactor-docs]: https://imperavi.com/assets/pdf/redactor-documentation-10.pdf

content/collections/tags/theme-asset.md

@@ -12,6 +12,12 @@ parameters:
     description: >
       The path to the file, relative to the
       theme directory.
+  -
+    name: cache_bust
+    type: 'boolean *false*'
+    description: >
+      Setting this to `true` will add the timestamp of the asset to the end of
+      the URL in a `?v=` query param.
 id: de348605-5489-4282-9257-bd9ffd92438e
 ---
 ## Explicit mode {#explicit-mode}

content/collections/tags/theme-css.md

@@ -20,6 +20,13 @@ parameters:
       theme assets, setting this to `true`
       will use the manifest to output the
       filename.
+  -
+    name: cache_bust
+    type: 'boolean *false*'
+    description: >
+      Setting this to `true` will add the timestamp of the asset to the end of
+      the URL in a `?v=` query param. Use this to version files if you are
+      _not_ using Elixir.
 id: 6b5093dc-dd82-4ae2-a9ff-53d4099d11e3
 ---
 ## Example {#example}

content/collections/tags/theme-js.md

@@ -17,6 +17,13 @@ parameters:
       theme assets, setting this to `true`
       will use the manifest to output the
       filename.
+  -
+    name: cache_bust
+    type: 'boolean *false*'
+    description: >
+      Setting this to `true` will add the timestamp of the asset to the end of
+      the URL in a `?v=` query param. Use this to version files if you are
+      _not_ using Elixir.
 ---
 ## Example {#example}
 ```

content/collections/tags/users.md

@@ -6,6 +6,14 @@ parameters:
     name: sort
     type: string *username*
     description: Sort entries by a field.
+  -
+    name: group
+    type: string
+    description: Specify the slug to filter users by a single group.
+  -
+    name: role
+    type: string
+    description: Specify the slug to filter users by a single role.
 id: c3e6df36-d705-4293-a5d8-40d27a06a18c
 ---
 This tag has the same functionality as the [collection](collection) tag, with some differences.

content/pages/3.addons/1.getting-started/2.code-structure/index.md

@@ -22,6 +22,16 @@ site/
         |-- Models/
         |   |-- Order.php
         |   └── Product.php
+        |-- resources/
+        |   |-- assets/
+        |   |   |-- js/
+        |   |   |-- css/
+        |   |   `-- img/
+        |   |-- lang/
+        |   |   `-- en/
+        |   |       `-- settings.php
+        |   `-- views/
+        |       `-- index.blade.php
         |-- BisonAPI.php
         |-- BisonController.php
         |-- BisonFieldtype.php
@@ -30,8 +40,12 @@ site/
         |-- BisonServiceProvider.php
         |-- BisonTags.php
         |-- BisonTasks.php
+        |-- BisonWidget.php
         |-- bootstrap.php
         |-- composer.json
+        |-- default.yaml
+        |-- routes.yaml
+        |-- settings.yaml
         └── meta.yaml
 ```
 

content/pages/3.addons/2.anatomy/10.controllers/index.md

@@ -32,7 +32,7 @@ class KarmaController extends Controller
 }
 ```
 
-Each public method in the controller can have a route pointed toward it. We can route to the controller action above by editing the routes array in our addon's `meta.yaml` file.
+Each public method in the controller can have a route pointed toward it. We can route to the controller action above by editing the routes array in our addon's `routes.yaml` file.
 
 ``` .language-yaml
 routes:
@@ -64,3 +64,7 @@ routes:
     uses: getEdit    
     as: karma.edit
 ```
+
+Note: If you want a settings page, you do _not_ need to create a route. A `/cp/addons/addon-name/settings` route
+will be available to you automatically. To avoid conflicts you should not create a route named `settings`.
+[See how to create a settings page](/addons/anatomy/settings).

content/pages/3.addons/2.anatomy/11.widget/index.md

@@ -0,0 +1,67 @@
+---
+overview: >
+  Widgets let you display anything you like on the Control Panel dashboard. From important sales data
+  to a random Chuck Norris joke of the day.
+title: Widgets
+id: c6a4207b-8477-48db-9a7f-576b9a714031
+---
+## Creating a Widget
+
+To create a widget, you will need a class file named `[AddonName]Widget.php`. eg. `ComplimentWidget.php`.
+
+You can also use `php please make:widget AddonName` to have one generated for you.
+
+Here's a basic widget:
+
+``` .language-php
+<?php
+
+namespace Statamic\Addons\Compliment;
+
+use Statamic\Extend\Widget;
+
+class ComplimentWidget extends Widget
+{
+    public function html()
+    {
+        return '<p>You look extra handsome today.</p>';
+    }
+}
+```
+
+Simply add an `html` method that returns a string. That's it.
+
+## Adding the widget to the dashboard
+
+In your Control Panel settings (`Configure > Settings > Control Panel` or `site/settings/cp.yaml`), add your widget
+to the array.
+
+```
+widgets:
+  -
+    type: compliment
+```
+
+## Configuring a widget
+
+You may add configuration options to your widget, much like parameters on tags or options in a fieldtype.
+
+Let's say we want to add the option to specify the `gender` receiving the compliment.
+
+``` .language-yaml
+widget:
+  type: compliment
+  gender: female
+```
+
+You can retrieve the config option within the Widget class by using `$this->getConfig('gender')`.
+
+``` .language-php
+public function html()
+{
+    $adjective = ($this->getConfig('gender', 'male') === 'male')
+        ? 'handsome' : 'beautiful';
+
+    return '<p>You look extra ' . $adjective . ' today.</p>';
+}
+```

content/pages/3.addons/2.anatomy/12.settings/index.md

@@ -0,0 +1,60 @@
+---
+overview: >
+  Addons can be configured using a number of settings. While these are stored in
+  a YAML file, it's simple to create a UI for editing these through the Control Panel.
+title: Settings
+id: 14266569-ed5c-4804-b36c-fc66e502491e
+---
+## Overview
+
+Instead of hard-coding values into your addon, you may allow them to be user-configurable. You may leverage this
+using configuration settings.
+
+``` .language-php
+// Instead of hardcoding values...
+$message = 'Hello John!';
+
+// Use a config setting!
+$name = $this->getConfig('greeting_name', 'John');
+$message = "Hello {$name}!";
+```
+
+You should add all your settings to `default.yaml` in your addon folder. As the filename suggests, these will
+act as the default values.
+
+If a user wants to override a setting they may create a `site/addons/addon_name.yaml` file and add the value
+in there. Note that the whole `default.yaml` doesn't need to be copied. Only the values that they wish to
+override need to be in there.
+
+## Creating a Settings UI {#ui}
+
+A nice alternative to opening YAML files is the ability to edit settings through the Control Panel.
+
+To allow your users to edit your configuration settings, simply create a `settings.yaml` fieldset
+in your addon's folder.
+
+``` .language-yaml
+fields:
+  foo:
+    type: text
+```
+
+You should _not_ include `display` or `instructions` values. Instead, these should be added to your addon's
+`resources/lang/en/settings.php` file.
+
+``` .language-php
+<?php
+return [
+    'foo' => 'Foo',
+    'foo_instruct' => "What's a foo? You tell me."
+];
+```
+
+Of course, these strings may be translated into other languages by using separate files.
+
+## Retrieving config settings
+
+You can use `$this->getConfig($value, $fallback)` (as well as the type-casting alternatives: `getConfigInt`,
+`getConfigBool`, etc) to retrieve a value.
+
+Config settings can be used from within any addon aspect.