Merge pull request #44 from visto9259/2.0.x

Prepared docs for release 2.0.0

docs/docusaurus.config.js

@@ -48,6 +48,14 @@ const config = {
               // Remove this to remove the "edit this page" links.
                 editUrl:
                 'https://github.com/lm-commons/lmcadmin/tree/master/docs/',
+                includeCurrentVersion: false,
+                lastVersion: '2.0',
+                versions: {
+                    "2.0": {
+                        label: '2.0',
+                        path: '2.0',
+                    }
+                }
             },
             blog: {
                 showReadingTime: true,

docs/src/pages/index.js

@@ -19,7 +19,7 @@ function HomepageHeader() {
             <div className={styles.buttons}>
                 <Link
                     className="button button--secondary button--lg"
-                    to="/docs/Introduction">
+                    to="/docs/2.0/Introduction">
                     Get Started
                 </Link>
             </div>

docs/versioned_docs/version-2.0/Authorization.md

@@ -0,0 +1,43 @@
+---
+sidebar_position: 4
+---
+# Authorization
+
+It is typical to implement some form of authorization to restrict access to admin functions to users with 
+administrative privileges.
+
+LmcAdmin does not prescribe a specific authorization framework.
+
+However, LmcAdmin can enable authorization via [LmcRbacMvc](https://lm-commons.github.io/LmcRbac). 
+
+## Authorization using LmcRbacMvc 
+
+Configuration for LmcRbacMvc module is provided to easily configure LmcAdmin.
+Authorization enables you to restrict access to `/admin` and every other page under LmcAdmin.
+
+To enable access restriction with LmcRbacMvc, install the module and enable it in your application. 
+
+There is a sample LmcRbacMvc configuration in the`config/lmcadmin.global.php.dist` file. 
+Copy this file over to your `config/autoload` directory.
+
+It provides LmcRbacMvc configuration to restrict access to users for the `/admin` route. 
+Only users in the "admin" group are allowed to access LmcAdmin pages.
+
+Uncomment the following lines:
+
+```php
+return [
+    /**
+     * Suggested LmcRbacMvc configuration for RBAC
+     */
+    'lmc_rbac' => [
+        'guards' => [
+            'Lmc\Rbac\Mvc\Guard\RouteGuard' => [
+                'lmcadmin*' => ['admin'],
+            ],
+        ],
+    ],
+];
+```
+
+Instructions for further configuration of LmcRbacMvc are provided in the LmcRbacMvc [documentation](https://lm-commons.github.io/LmcRbacMvc).

docs/versioned_docs/version-2.0/Introduction.md

@@ -0,0 +1,36 @@
+---
+sidebar_position: 1
+---
+# Getting Started
+LmcAdmin is a low-level module that helps Laminas MVC Framework developers to create an admin interface. 
+The module allows to have a uniform layout, navigation structure and routing scheme. 
+You can create controllers routed as a child of LmcAdmin, so you can easily change the (root) url, access control 
+and other properties. 
+The navigation is also flexible, to allow you having a structure built of pages in the admin interface with menus, 
+breadcrumbs and other links.
+
+## Requirements
+
+- PHP 8.1 and later
+- Laminas MVC 3.0 or later
+
+## Installation
+
+Install the module:
+
+```bash
+$ composer require lm-commons/lmc-admin
+```
+
+You will be prompted by the laminas-component-installer plugin to inject LM-Commons\LmcAdmin.
+
+:::note[Manual installation:]
+
+Enable the module by adding `Lmc\Admin` key to your `application.config.php` or `modules.config.php` file for Laminas MVC
+applications.
+:::
+
+Customize the module by copy-pasting
+the `config/lmcadmin.global.php.dist` file to your `config/autoload` folder.
+
+

docs/versioned_docs/version-2.0/Navigation.md

@@ -0,0 +1,27 @@
+---
+sidebar_position: 3
+---
+# Navigation
+LmcAdmin provides a dedicated navigation structure for the admin interface. 
+By default, LmcAdmin initiates a [Bootstrap](https://getbootstrap.com) layout on top the main admin navigation. 
+These admin buttons are customizable.
+
+## Add a page
+The admin structure requires at least a `label` for the navigation element and a `route` or `url` parameter for the link to be created. The `route` will use the `url()` view helper to construct a link. It is recommended to use [routes](Routes) in your child pages of LmcAdmin and therefore it is straightforward to use the `route` parameter in the navigation configuration.
+
+In the following example, there is a navigation element called "Users" and points to `lmcadmin/users` as a route. 
+This page is configured as follows:
+
+```php
+'navigation' => [
+    'admin' => [
+        'my-module' => [
+            'label' => 'Users',
+            'route' => 'lmcadmin/users',
+         ],
+    ],
+],
+```
+
+The navigation in LmcAdmin uses `Laminas\Navigation` and more information about the configuration of this component is 
+located in the [Laminas Navigation](https://docs.laminas.dev/laminas-navigation/) reference guide.

docs/versioned_docs/version-2.0/Routes.md

@@ -0,0 +1,74 @@
+---
+sidebar_position: 2
+---
+# Routes
+LmcAdmin defines a single route named `lmcadmin`, which is a `Laminas\Router\Http\Literal` route and mapped to the url `/admin`. 
+You can create child routes under `lmcadmin` so you can enable urls like `/admin/users` or `/admin/roles/permissions`.
+
+## Add child route
+To register a route as child route, the following example takes the option you name the route `users`. 
+The complete path should look like `/admin/users`, so `users` is a literal route with the route value `/users`. 
+Say you want this route to connect to the `MyAdminModule\Controller\UsersController` controller and the `index` action, 
+create this config in your `module.config.php`:
+
+```php
+'router' => [
+    'routes' => [
+        'lmcadmin' => [
+            'child_routes' => [
+                'users' => [
+                    'type' => Laminas\Router\Http\Literal::class,
+                    'options' => [
+                        'route' => '/users',
+                        'defaults' => [
+                            'controller' => MyAdminModule\Controller\UsersController::class,
+                            'action'     => 'index',
+                        ],
+                    ],
+                ],
+            ],
+        ],
+    ],
+],
+```
+
+## Change the `/admin` url
+If you want your admin interface at `/backend` or something else, you must override the value of the route. In the 
+following config, the `/admin` route value is replaced with `/backend`. Make sure this is enabled in a config where the 
+module is registered ***after*** LmcAdmin (otherwise, the config will not overwrite LmcAdmin's configuration):
+
+```php
+'router' => [
+    'routes' => [
+        'lmcadmin' => [
+            'options' => [
+                'route'    => '/backend',
+         ],
+    ],
+],
+```
+
+## Change the controller behind `/admin`
+By default, the `/admin` url links to the `LmcAdmin\Controller\AdminController` controller.
+`LmcAdmin\Controller\AdminController` is an simple action that only returns a simple view script. 
+If you want, for example, to create a dashboard on the admin index page, you probably need to point the route to 
+another controller. 
+In the following config, the `lmcadmin` route's controller is replaced with `MyAdminModule/Controller/AdminController` 
+and the action is set to `dashboard`. 
+Make sure this is enabled in a config where the module is registered ***later*** LmcAdmin (otherwise, the config will 
+not overwrite LmcAdmin's configuration):
+
+```php
+'router' => [
+    'routes' => [
+        'lmcadmin' => [
+            'options' => [
+                'defaults' => [
+                    'controller' => MyModule\Controller\AdminController::class,
+                    'action'     => 'dashboard',
+                ],
+            ],
+        ],
+    ],
+],
+```

docs/versioned_docs/version-2.0/Upgrading/to-v2.md

@@ -0,0 +1,22 @@
+---
+sidebar_label: From v1 to v2
+---
+# Upgrading from v1 to v2
+
+LmcAdmin v2 is a major version upgrade with many breaking changes that prevent
+straightforward upgrading.
+
+### Namespace change
+
+The namespace has been changed from LmcAdmin to Lmc\Admin.
+
+Please review your code to replace references to the `LmcAdmin` namespace
+by the `Lmc\Admin` namespace.
+
+### Default layout template name
+
+The default layout template has been changed from `layout/admin` to `layout/lmcadmin`.
+
+### Configuration key
+
+The configuration key for LmcAdmin was changed from `lmcadmin` to `lmc_admin`. 

docs/versioned_docs/version-2.0/ViewLayout.md

@@ -0,0 +1,93 @@
+---
+sidebar_position: 5
+title: Views & Layouts
+---
+# View and layout templates
+LmcAdmin includes an admin layout template and an index view template, such that LmcAdmin works out of the box. These view templates are fully 
+customizable, you can turn them off or render other templates. 
+All options are listed below.
+
+## Use the applications's default layout template
+
+You can disable LmcAdmin from using its own layout via configuration and the application's default layout
+will be used.
+The routing and navigation still works, but the application's default layout template will be used. 
+
+You can modify the configuration to disable the usage of LmcAdmin layout. 
+
+In `config/autoload/lmcadmin.global.php`:
+
+```php
+return [
+    'lmc_admin' => [
+        'use_admin_layout' => false
+    ],
+];
+```
+
+## Override the LmcAdmin layout template
+You can provide your own admin layout template. 
+
+First create a layout view template in your application and define the View Manager template map to list 
+your custom layout template. Then modify the LmcAdmin configuration to define the layout that LmcAdmin will use:
+
+In `config/autoload/lmcadmin.global.php`:
+
+```php
+return [
+    'lmc_admin' => [
+        'admin_layout_template' => 'myapp/myadminlayout',
+    ],
+];
+```
+
+And in your module config:
+
+```php
+return [
+    'view_manager' => [
+        'template_map' => [
+            'myapp/myadminlayout' => '/path/to/your/layout/template'
+        ],
+    ],
+];
+```
+
+## Override the view template for the `AdminController` index action
+
+You can also define the template rendered when you visit `/admin` which defaults to `AdminController::indexAction()`
+
+`AdminController::indexAction()` will return a View Model using the template `lmc-admin/admin/index`.
+
+Therefore, you can override the template via the View Manager template map.
+
+In your module config:
+
+```php
+return [
+    'view_manager' => [
+        'template_map' => [
+            'lmc-admin/admin/index' => '/path/to/your/template'
+        ],
+    ],
+];
+```
+Make sure your module is registered in the `modules.config.php` ***after*** `LmcAdmin` to override LmcAdmin configuration.
+
+## Disable layout
+If you need a page within an admin controller where only the view template is rendered, 
+you can disable the layout. 
+Layout disabling works just like any other page outside LmcAdmin where you disable the layout. 
+To accomplish this, you must set the view model to 'terminal' in your controller:
+
+```php
+class MyAdminController extends AbstractActionController
+ {
+    public function someAction()
+    {
+        $model = new ViewModel;
+        $model->setTerminal(true);
+        return $model;
+    }
+}
+```

docs/versioned_sidebars/version-2.0-sidebars.json

@@ -0,0 +1,8 @@
+{
+  "documentationSidebar": [
+    {
+      "type": "autogenerated",
+      "dirName": "."
+    }
+  ]
+}

docs/versions.json

@@ -1,3 +1,4 @@
 [
+  "2.0",
   "1.2"
 ]