diff --git a/config/lmcadmin.global.php.dist b/config/lmcadmin.global.php.dist
index a31a4b3..dd6f4f8 100644
--- a/config/lmcadmin.global.php.dist
+++ b/config/lmcadmin.global.php.dist
@@ -8,36 +8,28 @@ declare(strict_types=1);
* If you have a ./config/autoload/ directory set up for your project, you can
* drop this config file in it and change the values as you wish.
*/
+return [
+ 'lmc_admin' => [
+ /**
+ * Flag to use layout/admin as the admin layout
+ *
+ * The layout when LmcAdmin is accessed will be set to an alternative layout,
+ * to distinguish the admin from the normal site. The layout is modified when
+ * the "admin" route or any subroute from "admin" is dispatched. Default is
+ * this setting true.
+ */
+ // 'use_admin_layout' => true,
-$settings = [
- /**
- * Flag to use layout/admin as the admin layout
- *
- * The layout when LmcAdmin is accessed will be set to an alternative layout,
- * to distinguish the admin from the normal site. The layout is modified when
- * the "admin" route or any subroute from "admin" is dispatched. Default is
- * this setting true.
- *
- * 'use_admin_layout' => true,
- *
- */
+ /**
+ * Layout template for LmcAdmin
+ *
+ * When use_admin_layout is set to true, this value will be used as template
+ * name for the admin layout. Default is 'layout/admin'
+ * Accepted is a string that resolves to a view script
+ */
+ // 'admin_layout_template' => 'layout/lmcadmin',
+ ],
- /**
- * Layout template for LmcAdmin
- *
- * When use_admin_layout is set to true, this value will be used as template
- * name for the admin layout. Default is 'layout/admin'
- *
- * 'admin_layout_template' => 'layout/admin',
- *
- * Accepted is a string that resolves to a view script
- */
-];
-/**
- * You do not need to edit below this line
- */
-return [
- 'lmc_admin' => $settings,
/**
* Suggested LmcRbacMvc configuration for RBAC
*/
diff --git a/docs/docs/Authorization.md b/docs/docs/Authorization.md
index 823c856..12b765d 100644
--- a/docs/docs/Authorization.md
+++ b/docs/docs/Authorization.md
@@ -2,11 +2,42 @@
sidebar_position: 4
---
# Authorization
-LmcAdmin allows authorization via [LmcRbacMvc](https://github.com/LM-Commons/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.
-## LmcRbacMvc authorization
-LmcRbacMvc works with `Laminas\Permission\Rbac` as access restriction component. The LmcRbacMvc module combines `Laminas\Permission\Rbac` with the standard user module [LmcUser](https://github.com/LM-Commons/LmcUser). To enable access restriction with LmcRbacMvc, install the module and enable it in your `application.config.php`.
+It is highly suggested to implement some form of authorization to restrict access to admin functions to users with
+administrative privileges.
-Furthermore, LmcAdmin has a `lmcadmin.global.php` file in the `/config` directory. Copy this file over to your `config/autoload` directory. It directly provides LmcRbacMvc configuration to restrict access to users for the `/admin` route. Only users in the "admin" group are allowed to access LmcAdmin's pages.
+LmcAdmin does not prescribe a specific authorization framework.
-Instructions for further configuration of LmcRbacMvc are provided in the [repository of LmcRbacMvc](https://github.com/LM-Commons/LmcRbacMvc).
+However, LmcAdmin can allow 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/docs/Introduction.md b/docs/docs/Introduction.md
index cf738a6..251bb3a 100644
--- a/docs/docs/Introduction.md
+++ b/docs/docs/Introduction.md
@@ -1,13 +1,34 @@
---
sidebar_position: 1
---
-# Introduction
-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.
+# 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:
+
+$ 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.
-Every part of LmcAdmin is customizable. In the pages listed below futher configuration options are explained. This documentation consists of the following pages:
- 1. [Introduction](Introduction)
- 2. [Routes](Routes)
- 3. [Navigation](Navigation)
- 4. [Authorization](Authorization)
- 5. [Views & Layout](ViewLayout)
diff --git a/docs/docs/Navigation.md b/docs/docs/Navigation.md
index b8d0b72..e8226ba 100644
--- a/docs/docs/Navigation.md
+++ b/docs/docs/Navigation.md
@@ -2,22 +2,26 @@
sidebar_position: 3
---
# Navigation
-LmcAdmin allows a dedicated navigation structure for the admin interface. By default, LmcAdmin initiates a [Twitter Bootstrap](http://twitter.github.com/bootstrap) layout with on top the main admin navigation. These admin buttons are customizable.
+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 "My Module" and points to `lmcadmin/foo/bar` as a route. This page is configured as follows:
+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' => array(
- 'admin' => array(
- 'my-module' => array(
- 'label' => 'My Module',
- 'route' => 'lmcadmin/foo/bar',
- ),
- ),
- ),
+'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 Mvc Framework](https://docs.laminas.dev/laminas-navigation/quick-start/) reference guide.
+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/docs/Routes.md b/docs/docs/Routes.md
index d1c2719..8d72d00 100644
--- a/docs/docs/Routes.md
+++ b/docs/docs/Routes.md
@@ -2,60 +2,73 @@
sidebar_position: 2
---
# Routes
-LmcAdmin enables a single route named `lmcadmin`, which is a literal route and standard using the url `/admin`. You can create child routes under `lmcadmin` so you enable urls like `/admin/foo` or `/admin/bar/baz`.
+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`.
## Add child route
-To register a route as child route, the following example takes the option you name that route `foo`. The complete path should look like `/admin/foo`, so `foo` is a literal route with the route value `/foo`. Say you want this route to connect to your `MyModule\Controller\MyController` controller and the `index` action, create this config in your `module.config.php`:
+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' => array(
- 'routes' => array(
- 'lmcadmin' => array(
- 'child_routes' => array(
- 'foo' => array(
- 'type' => 'literal',
- 'options' => array(
- 'route' => '/foo',
- 'defaults' => array(
- 'controller' => 'MyModule\Controller\MyController',
- 'action' => 'index',
- ),
- ),
- ),
- ),
- ),
- ),
- ),
+'router' => [
+ 'routes' => [
+ 'lmcadmin' => [
+ 'child_routes' => [
+ 'users' => [
+ 'type' => 'literal',
+ '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 *later* than LmcAdmin (otherwise, the config will not overwrite LmcAdmin's configuration):
+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' => array(
- 'routes' => array(
- 'lmcadmin' => array(
- 'options' => array(
- 'route' => '/backend',
- ),
- ),
- ),
+'router' => [
+ 'routes' => [
+ 'lmcadmin' => [
+ 'options' => [
+ 'route' => '/backend',
+ ],
+ ],
+],
```
## 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. If you want, for example, 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 `MyModule/Controller/AdminController` and the action is set to `dashboard`. Make sure this is enabled in a config where the module is registered *later* than LmcAdmin (otherwise, the config will not overwrite LmcAdmin's configuration):
+By default, the `/admin` url links to the `LmcAdmin\Controller\AdminController` controller.
+It's an empty action and a simple view script is rendered.
+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' => array(
- 'routes' => array(
- 'lmcadmin' => array(
- 'options' => array(
- 'defaults' => array(
- 'controller' => 'MyModule/Controller/AdminController',
- 'action' => 'dashboard',
- ),
- ),
- ),
- ),
- ),
+'router' => [
+ 'routes' => [
+ 'lmcadmin' => [
+ 'options' => [
+ 'defaults' => [
+ 'controller' => 'MyModule/Controller/AdminController',
+ 'action' => 'dashboard',
+ ],
+ ],
+ ],
+ ],
+],
```
diff --git a/docs/docs/Upgrading/to-v2.md b/docs/docs/Upgrading/to-v2.md
new file mode 100644
index 0000000..67c4c2c
--- /dev/null
+++ b/docs/docs/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/docs/ViewLayout.md b/docs/docs/ViewLayout.md
index 16de206..06e63ce 100644
--- a/docs/docs/ViewLayout.md
+++ b/docs/docs/ViewLayout.md
@@ -3,63 +3,91 @@ sidebar_position: 5
title: View & Layout
---
# 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. All options are listed below.
+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.
+All options are listed below.
-## Override admin layout
-You can define your own layout script. If you want a custom layout template, you must create a module where this layout is defined. Then the resolver can automatically find a version of the layout if you configure your module correctly. Say you have a module `MyAdmin`, create a module configuration to load view scripts for that module in the `module.config.php`:
+## Use the applications's default layout
+
+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.
+
+You can modify the configuration to disable the usage of LmcAdmin layout.
+
+In `config/autoload/lmcadmin.global.php`:
```php
- 'view_manager' => array(
- 'template_path_stack' => array(
- __DIR__ . '/../view'
- ),
- ),
+return [
+ 'lmc_admin' => [
+ 'use_admin_layout' => false
+ ],
+];
```
-The MyAdmin module must contain a `view` directory. Inside this directory, create another directory called `layout` and inside `layout` create a file `admin.phtml`. So this file is located (if your MyAdmin module is under the `module/` directory of your application) at `module/MyAdmin/view/layout/admin.phtml`.
-Make sure MyAdmin is registered in the `application.config.php` and `LmcAdmin` is located *above* `MyAdmin`. Then your new admin template will be loaded.
+## Override the LmcAdmin layout
+You can provide your own admin layout script.
+
+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:
+
+In `config/autoload/lmcadmin.global.php`:
+
+```php
+return [
+ 'lmc_admin' => [
+ 'admin_layout_template' => 'myapp/myadminlayout',
+ ],
+];
+```
-## Override admin index view script
-You can also define the script rendered when you visit `/admin`. The way to solve this is similar to changing the layout (see above), only the location of the view script is different. So create a new module, for example MyAdmin, and enable this configuration:
+And in your module config:
```php
- 'view_manager' => array(
- 'template_path_stack' => array(
- __DIR__ . '/../view'
- ),
- ),
+return [
+ 'view_manager' => [
+ 'template_map' => [
+ 'myapp/myadminlayout' => '/path/to/your/layout/template/script'
+ ],
+ ],
+];
```
-Then create the folders `lmc-admin/admin` inside the `view` directory. Inside `lmc-admin/admin`, create an `index.phtml` file. So this file is located (if your MyAdmin module is under the `module/` directory of your application) at `module/MyAdmin/view/lmc-admin/admin/index.phtml`.
-Make sure MyAdmin is registered in the `application.config.php` and `LmcAdmin` is located *above* `MyAdmin`. Then your new index view script will be loaded.
+## Override the view script for the `AdminController` index action
-## Rename admin layout
-If you already have a `layout/admin` layout template and want to use another layout for LmcAdmin, you can rename the layout used. By default it is `layout/admin` but you can for example configure LmcAdmin to switch to `layout/backend`. You can enable this configuration to use another layout name:
+You can also define the script 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
- 'lmcadmin' => array(
- 'admin_layout_template' => 'layout/backend'
- ),
+return [
+ 'view_manager' => [
+ 'template_map' => [
+ 'lmc-admin/admin/index' => '/path/to/your/template/script'
+ ],
+ ],
+];
```
+Make sure your module is registered in the `modules.config.php` ***after*** `LmcAdmin` to override LmcAdmin configuration.
## Disable layout
-If you need a page with a controller where only the view script 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 the controller:
+If you need a page within an admin controller where only the view script 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:
```php
+class MyAdminController extends AbstractActionController
+ {
public function indexAction()
{
$model = new ViewModel;
$model->setTerminal(true);
-
return $model;
}
-```
-
-## Use normal `layout.phtml` layout
-You can disable LmcAdmin to switch to the `layout/admin` layout at all. The routing and navigation still works, but the name of the layout script is untouched. You can enable this configuration to disable layout switching:
-
-```php
- 'lmcadmin' => array(
- 'use_admin_layout' => false
- ),
+}
```
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
index 67a93e0..76f7f58 100644
--- a/docs/docusaurus.config.js
+++ b/docs/docusaurus.config.js
@@ -11,7 +11,7 @@ const ProjectName = 'LmcAdmin';
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'LmcAdmin',
- tagline: 'Admin interface for Laminas MVC framework',
+ tagline: 'Admin interface for Laminas MVC applications',
favicon: 'img/favicon.ico',
// Set the production url of your site here
@@ -75,59 +75,70 @@ themeConfig:
src: 'img/LMC-logo.png',
},
items: [
- {
- type: 'docSidebar',
- sidebarId: 'documentationSidebar',
- position: 'left',
- label: 'Documentation',
- },
- {to: '/blog', label: 'Blog', position: 'left'},
+ {
+ type: 'docSidebar',
+ sidebarId: 'documentationSidebar',
+ position: 'left',
+ label: 'Documentation',
+ },
+ //{to: '/blog', label: 'Blog', position: 'left'},
+ {
+ type: "docsVersionDropdown",
+ position: "right",
+ },
{
href: 'https://lm-commons.github.io',
label: 'LM-Commons',
position: 'right',
- },
- {
- href: `https://github.com/lm-commons/${ProjectName.toLowerCase()}`,
- label: 'GitHub',
- position: 'right',
- },
+ },
+ {
+ href: `https://github.com/lm-commons/${ProjectName.toLowerCase()}`,
+ //label: 'GitHub',
+ position: 'right',
+ className: 'header-github-link',
+ },
],
},
footer: {
style: 'dark',
links: [
- {
- title: 'Docs',
- items: [
- {
- label: 'Documentation',
- to: '/docs/Introduction',
- },
- ],
- },
- {
- title: 'Community',
- items: [
+ /*
{
- label: 'Slack',
- href: 'https://join.slack.com/t/lm-commons/shared_invite/zt-2gankt2wj-FTS45hp1W~JEj1tWvDsUHQ',
+ title: 'Docs',
+ items: [
+ {
+ label: 'Documentation',
+ to: '/docs/Introduction',
+ },
+ ],
},
- ],
- },
- {
- title: 'More',
- items: [
+
+ */
{
- label: 'Blog',
- to: '/blog',
+ title: 'Community',
+ items: [
+ {
+ label: 'Slack',
+ href: 'https://join.slack.com/t/lm-commons/shared_invite/zt-2gankt2wj-FTS45hp1W~JEj1tWvDsUHQ',
+ },
+ ],
},
{
- label: 'GitHub',
- href: `https://github.com/lm-commons/${ProjectName.toLowerCase()}`,
+ title: 'More',
+ items: [
+ /*
+ {
+ label: 'Blog',
+ to: '/blog',
+ },
+
+ */
+ {
+ label: 'GitHub',
+ href: `https://github.com/lm-commons/${ProjectName.toLowerCase()}`,
+ },
+ ],
},
- ],
- },
],
copyright: `Copyright © ${new Date().getFullYear()} LM-Commons Organization. Built with Docusaurus.`,
},
diff --git a/docs/src/css/custom.css b/docs/src/css/custom.css
index 2bc6a4c..5346a00 100644
--- a/docs/src/css/custom.css
+++ b/docs/src/css/custom.css
@@ -28,3 +28,19 @@
--ifm-color-primary-lightest: #4fddbf;
--docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}
+
+.header-github-link::before {
+ content: '';
+ width: 24px;
+ height: 24px;
+ display: flex;
+ background-color: var(--ifm-navbar-link-color);
+ mask-image: url("data:image/svg+xml,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E");
+ transition: background-color var(--ifm-transition-fast)
+ var(--ifm-transition-timing-default);
+}
+
+.header-github-link:hover::before {
+ background-color: var(--ifm-navbar-link-hover-color);
+}
+
diff --git a/docs/src/pages/index.js b/docs/src/pages/index.js
index 3264adc..7f2b77c 100644
--- a/docs/src/pages/index.js
+++ b/docs/src/pages/index.js
@@ -16,7 +16,6 @@ function HomepageHeader() {
{siteConfig.title}
{siteConfig.tagline}
- Part of the LM-Commons series of community developed packages for Laminas