Merge pull request #504 from ExpressionEngine/feature/7.x/add-on-controllers

ee7 docs for add-on controllers feature by @mithra62

Author: ops-andy

docs/development/addon-controllers/about.md

@@ -0,0 +1,188 @@
+# Add-on Controllers
+
+Add-on Controllers allows Add-on developers to create their Add-on methods using an abstracted object layer while keeping backwards compatibility intact. It covers Extensions, Modules (Action and Tags), and the Control Panel layers. It's very simple to implement (just inherit an object), while maintaining the legacy implementation in play. 
+
+To implement, you simply set your Add-on `mod.`, `ext.`, and/or `mcp.` files to inherit from a base object (depending on the implementation).
+
+## Add-on File Examples
+
+Here's a breakdown for how the Add-on files would look for an Add-on named `Custom_addon`.
+
+> Note that this works by using set or determined namespaces for a given Add-on. By default, this Controller implementation will use the Add-on name to get the configured namespace within the Add-on. For this example of `Custom_addon`, it's `YourAddon`; all route namespaces are determined by that. 
+
+### Module
+
+The `mod` file would consist exclusively of the below. 
+
+```php
+use ExpressionEngine\Service\Addon\Module;
+
+class Custom_addon extends Module
+{
+    protected $addon_name = 'custom_addon';
+}
+```
+
+Once that's done, your Add-on Module is now set to look for objects for all calls to it. Those objects depend on what "type" (Tag or Action). Using the configured namespace for the Add-on, the Module routes would be looked for in YourAddon\Module\Tags|Action`. 
+
+#### Template Tag 
+
+For a template tag called as `{exp:custom_addon:test_template_tag}`, you'd setup your Tag object like the below:
+
+```php
+namespace YourAddon\Module\Tags;
+
+use ExpressionEngine\Service\Addon\Controllers\Tag\AbstractRoute;
+
+class TestTemplateTag extends AbstractRoute
+{
+    public function process()
+    {
+
+    }
+}
+```
+
+#### Actions
+Just like with Template Tags, Actions get stored in the `Actions` namespace. The below is for an Action called `my-test-action`. 
+
+```php
+<?php
+namespace YourAddon\Module\Actions;
+
+use ExpressionEngine\Service\Addon\Controllers\Action\AbstractRoute;
+
+class MyTestAction extends AbstractRoute
+{
+    public function process()
+    {
+
+    }
+}
+```
+
+### Extension
+
+The `ext` is structured just like the others:
+
+```php
+use ExpressionEngine\Service\Addon\Extension;
+
+class Custom_addon_ext extends Extension
+{
+    protected $addon_name = 'custom_addon';
+}
+```
+
+Again, just like the others, Extensions are structured similarly.
+
+```php
+<?php
+namespace YourAddon\Extensions;
+
+use ExpressionEngine\Service\Addon\Controllers\Extension\AbstractRoute;
+
+class TestExtension extends AbstractRoute
+{
+    public function process()
+    {
+
+    }
+}
+```
+
+Note that the above `process` method allows you to accept variable parameters (just like regular Extensions). For example, to build an Extension around `template_post_parse`, you'd write your Extension like the below:
+
+```php
+namespace YourAddon\Extensions;
+
+use ExpressionEngine\Service\Addon\Controllers\Extension\AbstractRoute;
+
+class TestExtension extends AbstractRoute
+{
+    public function process(string $final_template, bool $is_partial, string $site_id, array $currentTemplateInfo): string
+    {
+        return $final_template;
+    }
+}
+```
+
+### Module Control Panel (MCP)
+
+The `mcp` layer acts more as a Controller/Router than the others in that the CP is supposed to be rendered as Views. To start, just like all the others, you extend from the `Mcp` object. Once that's done, all requests will be routed to the object layer. 
+
+```php
+use ExpressionEngine\Service\Addon\Mcp;
+
+class Custom_addon_mcp extends Mcp
+{
+    protected $addon_name = 'custom_addon';
+}
+```
+
+#### Route Examples
+
+A basic 'index' route (normally done through a method attached to the `mcp` object) would look like the below:
+
+```php
+namespace YourAddon\Mcp;
+
+use ExpressionEngine\Service\Addon\Controllers\Mcp\AbstractRoute;
+
+class Index extends AbstractRoute
+{
+    /**
+     * @var string
+     */
+    protected $route_path = 'index';
+
+    /**
+     * @var string
+     */
+    protected $cp_page_title = 'home';
+
+    /**
+     * @param false $id
+     * @return AbstractRoute
+     */
+    public function process($id = false): AbstractRoute
+    {
+        return $this;
+    }
+}
+```
+
+The generation of the CP array format is done automatically by the Controller so all the devs really do is assign variables and ensure their `process` method returns an instance of their Route:
+
+```php
+namespace YourAddon\Mcp;
+
+use ExpressionEngine\Service\Addon\Controllers\Mcp\AbstractRoute;
+
+class Index extends AbstractRoute
+{
+    /**
+     * @var string
+     */
+    protected $route_path = 'index';
+
+    /**
+     * @var string
+     */
+    protected $cp_page_title = 'home';
+
+    /**
+     * @param false $id
+     * @return AbstractRoute
+     */
+    public function process($id = false): AbstractRoute
+    {
+        $this->addBreadcrumb('test-link', 'test-link')
+             ->addBreadcrumb('test-link2', 'test-link2');
+
+        $variables = [];
+        $this->setBody('my-view', $variables);
+        return $this;
+    }
+}
+```

docs/development/addon-controllers/cp.md

@@ -0,0 +1,164 @@
+# Control Panel
+
+Just like with Extension and Module routing, you have to extend your ExpressionEngine Addon file to use the corresponding Add-on Controller Base route. In this case, that'll be `ExpressionEngine\Service\Addon\Mcp`.
+
+You'll also have to add a new property to your Control Panel object called `$route_namespace` which is the namespace for route objects.
+
+> Note the below example uses the `setRouteNamespace` method to set the `$route_namespace` property. 
+
+### Update Control Panel File
+
+```php
+use ExpressionEngine\Service\Addon\Mcp;
+
+class My_addon_mcp extends Cp
+{
+    protected $module_name = 'my_addon';
+
+    public function __construct()
+    {
+        $this->setRouteNamespace('MyAddon\Addon\Controllers');
+    }
+
+    public function index()
+    {
+        return $this->route('index', func_get_args());
+    }
+}
+
+```
+
+#### About `$route_namespace`
+
+Note that `$route_namespace` isn't directly one to one. The Add-on Controller does some magic to keep things compartmentalized.  Using the below example, the namespace used to locate your Route objects would be `Namespace\For\Your\Controllers\Cp\Routes`.
+
+#### About `$module_name`
+
+This value should contain the internal value ExpressionEngine uses to classify your parent Addon.
+
+> An extra special note about the use of `func_get_args()`: you should 100% keep doing that if you want Routing to be consistent. Basically, every declaration of a `route()` call should look like: `return $this->route('ROUTE_NAME', func_get_args());`
+
+### Create Control Panel Routes
+
+Unlike any other Controller Route, Control Panel routes require an addition to your ExpressionEngine Control Panel object. The idea is you tell ExpressionEngine to your object then the Router takes over. For example, in the above example, we define an `index` method and then route it internally. 
+
+The route object itself would look like the below:
+
+```php
+namespace YourAddon`\Addon\Controllers\Cp\Routes;
+
+use ExpressionEngine\Service\Addon\Mcp\AbstractRoute;
+
+class Index extends AbstractRoute
+{
+    protected $route_path = 'index';
+
+    public function process($id = false): AbstractRoute
+    {
+        return $this;
+    }
+}
+```
+
+You may have noticed that unlike traditional ExpressionEngine Control Panel methods, you don't return an array; you return an instance of your route instead. To generate output, the Router will take everything you setup within your object and pass that to ExpressionEngine. 
+
+#### About `$route_path`
+
+The value MUST contain the `noun|/verb` your Route is accessed through. See the for more details. 
+
+#### Full Example
+
+```php
+namespace YourAddon\Controllers\Mcp\Routes\ControllersExamples;
+
+use ExpressionEngine\Service\Addon\Mcp\AbstractRoute;
+
+class Cp extends AbstractRoute
+{
+    protected $route_path = 'controllers-examples/cp';
+
+    public function process($id = false): AbstractRoute
+    {
+        $this->setBody('test-route/my-action', []);
+        $this->setHeading('cp');
+
+        $this->addBreadcrumb($this->url('controllers-examples'), 'eo.cp.nav.controller.examples');
+        return $this;
+    }
+}
+```
+
+ 
+## Helper Functionality
+
+### Sidebar Generator
+
+To automatically generate your sidebar, you'll need to add a property to your Route object called `$sidebar_data` that contains an array that outlines your sidebar. 
+
+```php
+protected $sidebar_data = [
+    'eo.cp.nav.controller.examples' => [
+        'path' => 'controllers-examples',
+        'list' => [
+            'cp' => 'controllers-examples/cp',
+            'module' => 'controllers-examples/mod',
+        ]
+    ],
+    'eo.cp.nav.forms' => [
+        'path' => '',
+        'list' => [
+            'eo.cp.nav.example' => 'forms/example'
+        ]
+    ],
+    'eo.cp.nav.members' => [
+        'path' => '',
+        'list' => [
+            'eo.cp.nav.example' => 'members'
+        ]
+    ],
+    'eo.cp.nav.entries' => [
+        'path' => '',
+        'list' => [
+            'eo.cp.nav.example' => 'entries'
+        ]
+    ]
+];
+```
+
+Note the `$active_sidebar` property can be used to specify a specific sidebar node as having an `active` state. Otherwise, that'll be determined through the `$route_path` property. 
+
+### URL Helper
+
+To remove a considerable amount of keystrokes, you can use the `url($path, $with_base, $query)` method. What this does is allow you to create Control Panel URLs using the short syntax of a Route as well as any URL. 
+
+```php
+protected function url(string $path, bool $with_base = true, array $query = []): string
+```
+#### `$path` 
+
+Either the Router shortname for the route you want, or a full URL to the destination. 
+
+#### `$with_base`
+
+Boolean to compile the URL along with the `$base_url` property. If your link is to anything BUT a Route, you'll want this to be false. 
+
+#### `$query`
+
+An array of key=>values you want to use for the query string on the URL. 
+
+### Breadcrumbs
+
+You apply breadcrumbs using either the `addBreadcrumb($url, $text)` or the `setBreadcrumbs(array $breadcrumbs = [])` method(s). Note that `setBreadcrumbs` will completely reset any previously compiled `breadcrumb` items.
+
+```php
+protected function setBreadcrumbs(array $breadcrumbs = []): AbstractRoute
+protected function addBreadcrumb(string $url, string $text): AbstractRoute
+```
+
+### Body Content
+
+To output content within the ExpressionEngine Control Panel, you have to dictate both a view script to use and the variables to pass to it. 
+
+```php
+public function setBody(string $view, array $variables = []): AbstractRoute
+```

docs/development/addon-controllers/extensions.md

@@ -0,0 +1,38 @@
+# Extensions
+
+Just like with Module and Control Panel routing, you have to extend your ExpressionEngine Addon file to use the cooresponding Add-on Controller Base route. In this case, that'll be `ExpressionEngine\Service\Addon\Extension`.
+
+You'll also have to add a new property to your Extension called `$route_namespace` which is the namespace for route objects.
+
+### Update Extension File
+
+```php
+use ExpressionEngine\Service\Addon\Extension;
+
+class Your_addon_ext extends Extension
+{
+    protected $route_namespace = 'Namespace\For\Your\Controllers';
+}
+```
+
+#### About `$route_namespace`
+
+Note that `$route_namespace` isn't directly one to one. The Add-on Controller does some magic to keep things compartmentalized.  Using the below example, the namespace used to locate your Route objects would be `Namespace\For\Your\Controllers\Extensions\Routes`.
+
+### Create Route
+
+Note that your `process` method's signature should match up with the ExpressionEngine hooks passed parameters. 
+
+```php
+namespace YourAddon\Addon\Controllers\Extension\Routes;
+
+use ExpressionEngine\Service\Addon\Extension\AbstractRoute;
+
+class TemplatePostParse extends AbstractRoute
+{
+    public function process(string $final_template, bool $is_partial, int $site_id, array $currentTemplateInfo): string
+    {
+        return $final_template;
+    }
+}
+```