Merge branch 'release/1.1.0'

.gitignore

@@ -0,0 +1,2 @@
+assets/logo.svg
+*.xcf

CHANGELOG.md

@@ -1,3 +1,15 @@
+# v1.1.0
+## 08/08/2015
+
+1. [](#new)
+  * Added admin configurations **(requires Grav 0.9.34+)**
+  * Added `{{% comment %}}`, `{{% twig %}}`, `{{% markdown %}}` shortcodes
+  * Added documentation about `{{% raw %}}` shortcode
+  * Changed Shortcodes event to `onShortcodesInitialized`!
+2. [](#improved)
+  * Extended Twig Shortcodes capabilities for developers
+  * Updated `README.md`
+
 # v1.0.1
 ## 06/25/2015
 

LICENSE

@@ -8,10 +8,12 @@ For ease of distribution, Grav Shortcodes Plugin is under a dual license
 and is based on the principle of Give-and-Take.
 
 Unless otherwise noted Grav Shortcodes Plugin is licensed under the terms
-of GPLv3 http://opensource.org/licenses/GPL-3.0 (or see license text below).
+of GPLv3
+  http://opensource.org/licenses/GPL-3.0 (or see license text below).
 
-However it is licensed under the terms of MIT http://opensource.org/licenses/MIT
-(or see license text below) when the following conditions are met:
+However it is licensed under the terms of MIT
+  http://opensource.org/licenses/MIT (or see license text below)
+when the following conditions are met:
 
   - Grav Shortcodes Plugin is used, copied, merged, published for or
     distributed with Grav (http://getgrav.org)
@@ -44,7 +46,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
-
 GPL VERSION 3
 -------------
 

README.md

@@ -9,9 +9,9 @@
 * [About](#about)
 * [Installation and Updates](#installation-and-updates)
 * [Usage](#usage)
-  * [For end-users](#for-end-users)
-  * [For developers](#for-developers)
-  * [Available shortcodes](#available-shortcodes)
+    * [For end-users](#for-end-users)
+    * [For developers](#for-developers)
+    * [Available shortcodes](#available-shortcodes)
 * [Contributing](#contributing)
 * [Licencse](#license)
 
@@ -25,9 +25,9 @@
 
 ## Installation and Updates
 
-Installing or updating the `Shortcodes` plugin can be done in one of two ways. Using the GPM (Grav Package Manager) installation update method or manual install by downloading [this plugin](https://github.com/sommerregen/grav-plugin-shortcodes) and extracting all plugin files to
+Installing or updating the `Shortcodes` plugin can be done in one of two ways. Using the GPM (Grav Package Manager) installation update method or (i.e. `bin/gpm install shortcodes`) manual install by downloading [this plugin](https://github.com/sommerregen/grav-plugin-shortcodes) and extracting all plugin files to
 
-    /your/site/grav/user/plugins/shortcodes
+    user/plugins/shortcodes
 
 For more informations, please check the [Installation and update guide](docs/INSTALL.md).
 
@@ -45,26 +45,33 @@ enabled: true               # Set to false to disable this plugin completely
 # Default configurations for special shortcodes
 
 shortcodes:
-  twig:
+  assets:
     enabled: true
+    options:
+      type: "css"           # Assets type (either "css" or "js")
+      inline: false         # Include assets as block or inline argument
+      priority: 10          # Priority to add CSS or JS to Grav pipeline, bigger comes first
+      pipeline: false       # Pipeline assets or not
+      load: ""              # Load asset either asynchronously "async" or deferred "defer"
 
-  summary:
+  comment:
     enabled: true
 
   embed:
     enabled: true
     options:
       template: ""          # Default template to render a page
 
-  assets:
+  markdown:
     enabled: true
     options:
-      type: "css"           # Assets type (either "css" or "js")
-      inline: false         # Include assets as block or inline argument
-      priority: 10          # Priority to add CSS or JS to Grav pipeline, bigger comes first
-      pipeline: false       # Pipeline assets or not
-      load: ""              # Load asset either asynchronously "async" or deferred "defer"
+      extra: true           # Enable support for Markdown Extra
 
+  summary:
+    enabled: true
+
+   twig:
+    enabled: true
 ```
 
 If you need to change any value, then the best process is to copy the [shortcodes.yaml](shortcodes.yaml) file into your `users/config/plugins/` folder (create it if it doesn't exist), and then modify there. This will override the default settings.
@@ -124,12 +131,15 @@ The `Shortcodes` plugin offers some of the shortcodes by default and plugins can
 
 ##### System
 
-- `{{% embed %}}` embeds a page or the contents of a page. [» Full instructions](docs/embed.md)
 - `{{% assets %}}` adds CSS and JS assets directly to the site. [» Full instructions](docs/assets.md)
+- `{{% embed %}}` embeds a page or the contents of a page. [» Full instructions](docs/embed.md)
+- `{{% markdown %}}`is a shortcut to parse texts using Markdown syntax in a document. [» Full instructions](docs/markdown.md)
 - `{{% twig %}}` renders custom texts using the Twig templating engine. [» Full instructions](docs/twig.md)
 
 ##### Images and Documents
 
+- `{{% comment %}}` allows you to use comments and annotations in a Markdown document without being outputted to the user. [» Full instructions](docs/comment.md)
+- `{{% raw %}}` marks sections as being raw text that should not be parsed. [» Full instructions](docs/raw.md)
 - `{{% summary %}}` sets the summary of page. [» Full instructions](docs/summary.md)
 
 ##### Audio
@@ -142,51 +152,83 @@ Useful shortcodes for adding a blog archive index, contact form, polls, and more
 
 ## For developers
 
-The `Shortcodes` plugin offers developers to register their own shortcodes (here: `myshortcode`). To do this `Shortcodes` provides an event `onShortcodesEvent`, which could be used to register new shortcodes via
+The `Shortcodes` plugin offers developers to register their own shortcodes (here: `myblockshortcode` and `myinlineshortcode`). To do this `Shortcodes` provides an event `onShortcodesInitialized`, which could be used to register new shortcodes via the provided `Grav\Plugin\Shortcodes\Shortcodes::register` method. For example in your custom plugin use
 
 ```php
-class MyShortcode extends Plugin
+namespace Grav\Plugin;
+
+use Grav\Plugin\Shortcodes;
+
+class MyPlugin extends Plugin
 {
   public static function getSubscribedEvents()
   {
     return [
-    'onShortcodesEvent' => ['onShortcodesEvent', 0]
+      'onShortcodesInitialized' => ['onShortcodesInitialized', 0]
     ];
   }
 
-  ...
-
-  public function onShortcodesEvent(Event $event)
+  public function onShortcodesInitialized(Event $event)
   {
     // Initialize custom shortcode
-    $shortcode = new MyShortCode();
+    $shortcode = new MyShortcodes();
 
-    // Register shortcode
+    // Create block shortcode
+    $block = new Shortcodes\BlockShortcode('myblockshortcode', [$shortcode, 'block']);
+
+    // Create inline shortcode
+    $inline = new Shortcodes\InlineShortcode('myinlineshortcode', [$shortcode, 'inline']);
+
+    // Register shortcodes
+    $event['shortcodes']->register($block);
+    $event['shortcodes']->register($inline);
+
+    // Or register shortcodes from class (calls getShortcodes internally)
     $event['shortcodes']->register($shortcode);
   }
 }
 ```
 
-The `MyShortCode` class has basically the format
+The `MyShortcodes` class has basically the format
 
 ```php
+namespace Grav\Plugin;
+
+use Grav\Plugin\Shortcodes;
 use RocketTheme\Toolbox\Event\Event;
-use Grav\Plugin\Shortcodes\Shortcode;
 
-class MyShortCode extends Shortcode
+class MyShortcodes
 {
-  public function getShortcode()
+  public function getShortcodes()
   {
-    return ['name' => 'myshortcode', 'type' => 'block'];
+    $options = [];
+
+    return [
+      new Shortcodes\BlockShortcode('myblockshortcode', [$this, 'block'], $options).
+      new Shortcodes\InlineShortcode('myinlineshortcode', [$this, 'inline'], $options)
+    ];
   }
 
-  public function execute(Event $event)
+  public function block(Event $event)
+  {
+    // do something and return string
+  }
+
+  public function inline(Event $event)
   {
     // do something and return string
   }
 }
 ```
-where you can put your code inside the `execute()` method. Here the special method `getShortcode()` returns some informations about your shortcode i.e, that the name should be "myshortcode" and that it is a block element. That's it.
+where `myblockshortcode` and `myinlineshortcode` are placeholders for your block and inline shortcode names respectively. When `{{% myblockshortcode %}}...{{% end %}}` is found in the text the method `block` is called and `inline` when `{{% myinlineshortcode %}}` is found. The `event` argument is an array of
+
+- the body text ("body")
+- the options passed to the shortcode ("options")
+- the grav instance ("grav")
+- the shortcodes instance ("shortcodes")
+- the current page ("page")
+
+which can be used in your custom functions.
 
 For further examples, please study the already available shortcodes in the [provided shortcodes classes](classes/Shortcodes).
 

blueprints.yaml

@@ -1,5 +1,5 @@
 name: "Shortcodes"
-version: 1.0.1
+version: 1.1.0
 description: "This plugin enables to use shortcodes (simple snippets) inside a document to be rendered by Grav."
 icon: puzzle-piece
 author:
@@ -14,13 +14,86 @@ license: MIT/GPL
 form:
   validation: strict
   fields:
-    enabled:
-      type: toggle
-      label: "Plugin Status"
-      highlight: 1
-      default: 0
-      options:
-        1: Enabled
-        0: Disabled
-      validate:
-        type: bool
+    global:
+      type: section
+      title: "Global plugin configurations"
+      underline: 1
+
+      fields:
+        enabled:
+          type: toggle
+          label: "Plugin Status"
+          highlight: 1
+          default: 0
+          options:
+            1: "Enabled"
+            0: "Disabled"
+          validate:
+            type: bool
+
+    default:
+      type: section
+      title: "Default configurations for special shortcodes"
+      underline: 1
+
+      fields:
+        shortcodes.assets.enabled:
+          type: toggle
+          label: "Activate <code>{{% assets %}}</code> shortcode"
+          default: 0
+          options:
+            1: "Yes"
+            0: "No"
+          validate:
+            type: bool
+
+        shortcodes.comment.enabled:
+          type: toggle
+          label: "Activate <code>{{% comment %}}</code> shortcode"
+          default: 0
+          options:
+            1: "Yes"
+            0: "No"
+          validate:
+            type: bool
+
+        shortcodes.embed.enabled:
+          type: toggle
+          label: "Activate <code>{{% embed %}}</code> shortcode"
+          default: 0
+          options:
+            1: "Yes"
+            0: "No"
+          validate:
+            type: bool
+
+        shortcodes.markdown.enabled:
+          type: toggle
+          label: "Activate <code>{{% markdown %}}</code> shortcode"
+          default: 0
+          options:
+            1: "Yes"
+            0: "No"
+          validate:
+            type: bool
+
+        shortcodes.summary.enabled:
+          type: toggle
+          label: "Activate <code>{{% summary %}}</code> shortcode"
+          default: 0
+          options:
+            1: "Yes"
+            0: "No"
+          validate:
+            type: bool
+
+        shortcodes.twig.enabled:
+          type: toggle
+          label: "Activate <code>{{% twig %}}</code> shortcode"
+          default: 0
+          options:
+            1: "Yes"
+            0: "No"
+          validate:
+            type: bool
+

classes/BlockShortcode.php

@@ -0,0 +1,29 @@
+<?php
+/**
+ * BlockShortcode
+ *
+ * This file is part of Grav Shortcodes plugin.
+ *
+ * Dual licensed under the MIT or GPL Version 3 licenses, see LICENSE.
+ * http://benjamin-regler.de/license/
+ */
+
+namespace Grav\Plugin\Shortcodes;
+
+/**
+ * BlockShortcode
+ */
+class BlockShortcode extends Twig\GenericShortcode
+{
+  /**
+   * Constructor
+   *
+   * @param string    $name     Name of the shortcode.
+   * @param callable  $callable Callable to call for the shortcode.
+   * @param array     $options  An array of shortcode options.
+   */
+  public function __construct($name, $callable, array $options = array())
+  {
+    parent::__construct($name, $callable, 'block', $options);
+  }
+}

classes/InlineShortcode.php

@@ -0,0 +1,29 @@
+<?php
+/**
+ * InlineShortcode
+ *
+ * This file is part of Grav Shortcodes plugin.
+ *
+ * Dual licensed under the MIT or GPL Version 3 licenses, see LICENSE.
+ * http://benjamin-regler.de/license/
+ */
+
+namespace Grav\Plugin\Shortcodes;
+
+/**
+ * InlineShortcode
+ */
+class InlineShortcode extends Twig\GenericShortcode
+{
+  /**
+   * Constructor
+   *
+   * @param string    $name     Name of the shortcode.
+   * @param callable  $callable Callable to call for the shortcode.
+   * @param array     $options  An array of shortcode options.
+   */
+  public function __construct($name, $callable, array $options = array())
+  {
+    parent::__construct($name, $callable, 'inline', $options);
+  }
+}