Merge pull request #10 from dotkernel/documentation_update

Documentation update

Author: arhimede

docs/book/v1/how-tos/create-pages.md

@@ -1,17 +1,24 @@
 # Creating pages
 
-## The `action` function
+## Register the page route
 
-The first step is to add the new pages in `src/Page/src/Controller/PageController.php`.
-This means adding an `Action` function for each page, as seen below.
+Open `config/autoload/local.php` and locate the **routes** key.
+Under the **page** key you will find an associative array with a couple of already existing routes.
+You create a new route by appending a new line to that array:
 
 ```php
-    public function examplePageAction(): ResponseInterface
-    {
-        return new HtmlResponse(
-            $this->template->render('page::example-template')
-        );
-    }
+'example-page' => 'example-template',
+```
+
+> The array key is the page slug, the array value is the template name used by that page.
+
+In order to be displayed this new `example-template` needs to be added to the website's navigation area.
+To do this, open `src/App/templates/layout/default.html.twig`, locate the `ul` inside the `div` with id `navbarHeader` and append the below code to it:
+
+```twig
+    <li class="nav-item">
+        <a class="nav-link" href="{{ url('page::example-template') }}">Example</a>
+    </li>
 ```
 
 ## The page content
@@ -77,6 +84,3 @@ public function getTemplates(): array
 ## Accessing the page
 
 The url for the new page in this example is `/page/example-page`.
-
-> Because of the way routing works, dot (.), dash (-), underscore (_) are filtered from the `action` parameter in the routing `/page[/{action}]`.
-> As a result, the `examplePageAction` function in called.

docs/book/v1/how-tos/routing.md

@@ -0,0 +1,41 @@
+# Routing
+
+In our current implementation we are using request handlers instead of controllers in order for DotKernel to comply with the PSR-15 standard.
+
+## How are we implementing handlers?
+
+### Declaration of the routes and modules
+
+Currently, our structure uses modules, routes and template names.
+Those are being declared in the file `config/autoload/local.php` in the following way:
+
+```php
+    'routes'      => [
+        'page' => [
+            'about'      => 'about',
+            'who-we-are' => 'who-we-are',
+        ],
+    ],
+```
+
+In this case `page` represents the module and `'about' => 'about'` represents the page slug and its assigned `.twig` template.
+To clarify, this creates a route called `page.about` in the `page` module, it loads the template file `src/Page/templates/page/about.html.twig` and can be accessed at `/page/about`.
+With each request, when matching one of these routes, the `PageHandler` will detect the current route name and render the matching template.
+
+### Manipulating the declared routes and modules
+
+Each module has a `RoutesDelegator.php` file (ex. `src/Page/src/RoutesDelegator.php`).
+In this file we are retrieving the application config from the container and we loop over each module and their assigned routes.
+
+```php
+    $routes = $container->get('config')['routes'] ?? [];
+    foreach ($routes as $moduleName => $moduleRoutes) {
+        foreach ($moduleRoutes as $routeUri => $templateName) {
+            $app->get(
+                sprintf('/%s/%s', $moduleName, $routeUri),
+                [PageHandler::class],
+                sprintf('%s::%s', $moduleName, $templateName)
+            );
+        }
+    }
+```

docs/book/v1/installation/configuration-files.md

@@ -1,6 +1,6 @@
 # Dotkernel light
 
-Dotkernel Light is an application (skeleton) using Mezzio microframework and Laminas components.
+Dotkernel Light is a PSR-15 compliant application (skeleton) using Mezzio microframework and Laminas components.
 It's designed as a minimal project to generate a simple website, like a presentation site.
 
 Read on to find out more about the application:
@@ -12,7 +12,7 @@ Read on to find out more about the application:
 > Check out our [demo](https://light.dotkernel.net/).
 
 ![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/light)
-![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/light/1.0.0)
+![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/light/1.1.0)
 
 [![GitHub issues](https://img.shields.io/github/issues/dotkernel/light)](https://github.com/dotkernel/light/issues)
 [![GitHub forks](https://img.shields.io/github/forks/dotkernel/light)](https://github.com/dotkernel/light/network)

docs/book/v1/introduction.md

@@ -16,12 +16,12 @@ nav:
       - Installation:
           - "Getting Started": v1/installation/getting-started.md
           - "Composer": v1/installation/composer.md
-          - "Configuration Files": v1/installation/configuration-files.md
           - "Development Mode": v1/installation/development-mode.md
           - "Running the Application": v1/installation/running-the-application.md
           - "FAQ": v1/installation/faq.md
       - How to:
           - "Use NPM Commands": v1/how-tos/npm-commands.md
+          - "Routing": v1/how-tos/routing.md
           - "Create Pages": v1/how-tos/create-pages.md
           - "Set Up Twitter and OpenGraph Cards": v1/how-tos/twitter-opengraph-cards.md
           - "Edit the Top Menu": v1/how-tos/edit-top-menu.md