From 65a9186702ea060f59161e83b2ba302f684a447c Mon Sep 17 00:00:00 2001 From: "Eric Richer eric.richer@vistoconsulting.com" Date: Mon, 9 Sep 2024 14:10:58 -0400 Subject: [PATCH] Prepared docs for release 2.0.0 --- docs/docusaurus.config.js | 8 ++ docs/src/pages/index.js | 2 +- .../version-2.0/Authorization.md | 43 +++++++++ .../version-2.0/Introduction.md | 36 +++++++ docs/versioned_docs/version-2.0/Navigation.md | 27 ++++++ docs/versioned_docs/version-2.0/Routes.md | 74 +++++++++++++++ .../version-2.0/Upgrading/to-v2.md | 22 +++++ docs/versioned_docs/version-2.0/ViewLayout.md | 93 +++++++++++++++++++ .../version-2.0-sidebars.json | 8 ++ docs/versions.json | 1 + 10 files changed, 313 insertions(+), 1 deletion(-) create mode 100644 docs/versioned_docs/version-2.0/Authorization.md create mode 100644 docs/versioned_docs/version-2.0/Introduction.md create mode 100644 docs/versioned_docs/version-2.0/Navigation.md create mode 100644 docs/versioned_docs/version-2.0/Routes.md create mode 100644 docs/versioned_docs/version-2.0/Upgrading/to-v2.md create mode 100644 docs/versioned_docs/version-2.0/ViewLayout.md create mode 100644 docs/versioned_sidebars/version-2.0-sidebars.json diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 76f7f58..48f4db3 100644 --- a/docs/docusaurus.config.js +++ b/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, diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js index 7f2b77c..798369d 100644 --- a/docs/src/pages/index.js +++ b/docs/src/pages/index.js @@ -19,7 +19,7 @@ function HomepageHeader() {
+ to="/docs/2.0/Introduction"> Get Started
diff --git a/docs/versioned_docs/version-2.0/Authorization.md b/docs/versioned_docs/version-2.0/Authorization.md new file mode 100644 index 0000000..137d82a --- /dev/null +++ b/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). diff --git a/docs/versioned_docs/version-2.0/Introduction.md b/docs/versioned_docs/version-2.0/Introduction.md new file mode 100644 index 0000000..c92df08 --- /dev/null +++ b/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. + + diff --git a/docs/versioned_docs/version-2.0/Navigation.md b/docs/versioned_docs/version-2.0/Navigation.md new file mode 100644 index 0000000..e8226ba --- /dev/null +++ b/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. diff --git a/docs/versioned_docs/version-2.0/Routes.md b/docs/versioned_docs/version-2.0/Routes.md new file mode 100644 index 0000000..34e09e2 --- /dev/null +++ b/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', + ], + ], + ], + ], +], +``` diff --git a/docs/versioned_docs/version-2.0/Upgrading/to-v2.md b/docs/versioned_docs/version-2.0/Upgrading/to-v2.md new file mode 100644 index 0000000..67c4c2c --- /dev/null +++ b/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`. diff --git a/docs/versioned_docs/version-2.0/ViewLayout.md b/docs/versioned_docs/version-2.0/ViewLayout.md new file mode 100644 index 0000000..cd4bdcb --- /dev/null +++ b/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; + } +} +``` diff --git a/docs/versioned_sidebars/version-2.0-sidebars.json b/docs/versioned_sidebars/version-2.0-sidebars.json new file mode 100644 index 0000000..5f41a72 --- /dev/null +++ b/docs/versioned_sidebars/version-2.0-sidebars.json @@ -0,0 +1,8 @@ +{ + "documentationSidebar": [ + { + "type": "autogenerated", + "dirName": "." + } + ] +} diff --git a/docs/versions.json b/docs/versions.json index a869fac..4717ca9 100644 --- a/docs/versions.json +++ b/docs/versions.json @@ -1,3 +1,4 @@ [ + "2.0", "1.2" ]