Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updated docs for v2 #37

Merged
merged 2 commits into from
Sep 5, 2024
Merged

Updated docs for v2 #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
917891c
Beautify the file
visto9259 Sep 5, 2024
b981630
V2 docs
visto9259 Sep 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 20 additions & 28 deletions config/lmcadmin.global.php.dist
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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