From ca5349e5d219869a6aa6f987e4a342f8b86e96c1 Mon Sep 17 00:00:00 2001 From: "Eric Richer eric.richer@vistoconsulting.com" Date: Fri, 6 Sep 2024 11:28:18 -0400 Subject: [PATCH] Updates to v2 docs --- .github/workflows/deploy-gh-pages.yml | 2 +- docs/docs/Authorization.md | 4 ++-- docs/docs/Introduction.md | 4 +++- docs/docs/Routes.md | 14 +++++------ docs/docs/ViewLayout.md | 34 +++++++++++++-------------- src/ConfigProvider.php | 8 ++++--- 6 files changed, 35 insertions(+), 31 deletions(-) diff --git a/.github/workflows/deploy-gh-pages.yml b/.github/workflows/deploy-gh-pages.yml index 5a6a1fc..c87f06e 100644 --- a/.github/workflows/deploy-gh-pages.yml +++ b/.github/workflows/deploy-gh-pages.yml @@ -8,7 +8,7 @@ defaults: on: push: branches: - - 'master' + - 'main' paths: - 'docs/**' workflow_dispatch: diff --git a/docs/docs/Authorization.md b/docs/docs/Authorization.md index 12b765d..137d82a 100644 --- a/docs/docs/Authorization.md +++ b/docs/docs/Authorization.md @@ -3,12 +3,12 @@ sidebar_position: 4 --- # Authorization -It is highly suggested to implement some form of authorization to restrict access to admin functions to users with +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 allow authorization via [LmcRbacMvc](https://lm-commons.github.io/LmcRbac). +However, LmcAdmin can enable authorization via [LmcRbacMvc](https://lm-commons.github.io/LmcRbac). ## Authorization using LmcRbacMvc diff --git a/docs/docs/Introduction.md b/docs/docs/Introduction.md index 251bb3a..c92df08 100644 --- a/docs/docs/Introduction.md +++ b/docs/docs/Introduction.md @@ -18,13 +18,15 @@ breadcrumbs and other links. 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 +Enable the module by adding `Lmc\Admin` key to your `application.config.php` or `modules.config.php` file for Laminas MVC applications. ::: diff --git a/docs/docs/Routes.md b/docs/docs/Routes.md index 8d72d00..34e09e2 100644 --- a/docs/docs/Routes.md +++ b/docs/docs/Routes.md @@ -2,8 +2,8 @@ sidebar_position: 2 --- # Routes -LmcAdmin enables a single route named `lmcadmin`, which is a literal route and mapped to the url `/admin`. -You can create child routes under `lmcadmin` so you enable urls like `/admin/users` or `/admin/roles/permissions`. +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`. @@ -17,11 +17,11 @@ create this config in your `module.config.php`: 'lmcadmin' => [ 'child_routes' => [ 'users' => [ - 'type' => 'literal', + 'type' => Laminas\Router\Http\Literal::class, 'options' => [ 'route' => '/users', 'defaults' => [ - 'controller' => 'MyAdminModule\Controller\UsersController::class', + 'controller' => MyAdminModule\Controller\UsersController::class, 'action' => 'index', ], ], @@ -49,8 +49,8 @@ module is registered ***after*** LmcAdmin (otherwise, the config will not overwr ``` ## Change the controller behind `/admin` -By default, the `/admin` url links to the `LmcAdmin\Controller\AdminController` controller. -It's an empty action and a simple view script is rendered. +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` @@ -64,7 +64,7 @@ not overwrite LmcAdmin's configuration): 'lmcadmin' => [ 'options' => [ 'defaults' => [ - 'controller' => 'MyModule/Controller/AdminController', + 'controller' => MyModule\Controller\AdminController::class, 'action' => 'dashboard', ], ], diff --git a/docs/docs/ViewLayout.md b/docs/docs/ViewLayout.md index 06e63ce..cd4bdcb 100644 --- a/docs/docs/ViewLayout.md +++ b/docs/docs/ViewLayout.md @@ -1,17 +1,17 @@ --- sidebar_position: 5 -title: View & Layout +title: Views & Layouts --- -# View and layout scripts -LmcAdmin includes an admin layout and index view script, so LmcAdmin works out of the box. These view scripts are fully -customizable, you can turn them off or render other scripts. +# 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 +## 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 applicaiton's default layout script 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. @@ -25,11 +25,11 @@ return [ ]; ``` -## Override the LmcAdmin layout -You can provide your own admin layout script. +## Override the LmcAdmin layout template +You can provide your own admin layout template. -First create a layout view script in your application and define the View Manager template map to list -your custom layout script. Then modify the LmcAdmin configuration to define the layout that LmcAdmin will use: +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`: @@ -47,15 +47,15 @@ And in your module config: return [ 'view_manager' => [ 'template_map' => [ - 'myapp/myadminlayout' => '/path/to/your/layout/template/script' + 'myapp/myadminlayout' => '/path/to/your/layout/template' ], ], ]; ``` -## Override the view script for the `AdminController` index action +## Override the view template for the `AdminController` index action -You can also define the script rendered when you visit `/admin` which defaults to `AdminController::indexAction()` +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`. @@ -67,7 +67,7 @@ In your module config: return [ 'view_manager' => [ 'template_map' => [ - 'lmc-admin/admin/index' => '/path/to/your/template/script' + 'lmc-admin/admin/index' => '/path/to/your/template' ], ], ]; @@ -75,15 +75,15 @@ return [ 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 script is rendered, +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 terminate the view model in your controller: +To accomplish this, you must set the view model to 'terminal' in your controller: ```php class MyAdminController extends AbstractActionController { - public function indexAction() + public function someAction() { $model = new ViewModel; $model->setTerminal(true); diff --git a/src/ConfigProvider.php b/src/ConfigProvider.php index d5259c4..ba94717 100644 --- a/src/ConfigProvider.php +++ b/src/ConfigProvider.php @@ -1,8 +1,10 @@ [ 'lmcadmin' => [ - 'type' => 'literal', - 'options' => [ + 'type' => Literal::class, + 'options' => [ 'route' => '/admin', 'defaults' => [ 'controller' => Controller\AdminController::class,