Skip to content

Commit

Permalink
Merge pull request #37 from visto9259/2.0.x
Browse files Browse the repository at this point in the history 
Updated docs for v2
  • Loading branch information
@visto9259
visto9259 authored Sep 5, 2024
2 parents 0b1b6dc + b981630 commit fc158f3
Show file tree
Hide file tree
Showing 18 changed files with 502 additions and 183 deletions.
48 changes: 20 additions & 28 deletions config/lmcadmin.global.php.dist
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
*/
Expand Down
41 changes: 36 additions & 5 deletions docs/docs/Authorization.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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).
37 changes: 29 additions & 8 deletions docs/docs/Introduction.md
View file
Original file line number Diff line number Diff line change
@@ -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)
26 changes: 15 additions & 11 deletions docs/docs/Navigation.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
97 changes: 55 additions & 42 deletions docs/docs/Routes.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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',
],
],
],
],
],
```
22 changes: 22 additions & 0 deletions docs/docs/Upgrading/to-v2.md
View file
Original file line number Diff line number Diff line change
@@ -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`.
Loading

0 comments on commit fc158f3

Please sign in to comment.