Skip to content

Commit 10ec1aa

Browse files
author
Jurian Sluiman
committed
Merge pull request #14 from juriansluiman/feature/docs
Documentation
2 parents e41eac0 + 3b7d692 commit 10ec1aa

File tree

6 files changed

+190
-92
lines changed

6 files changed

+190
-92
lines changed

‎README.md‎

Lines changed: 8 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -1,102 +1,18 @@
11
# ZfcAdmin Module for Zend Framework 2
2-
3-
Version 0.0.1 Created by [Jurian Sluiman](http://juriansluiman.nl/en/) and [Martin Shwalbe](https://github.com/Hounddog)
2+
Version 0.1.0 created by [Jurian Sluiman](http://juriansluiman.nl/en) and [Martin Shwalbe](https://github.com/Hounddog).
43

54
## Introduction
6-
7-
soon to come
5+
ZfcAdmin is a minimal admin interface for generic administrative purposes. It is a common screen with navigation that hides behind authentication and authorization.
86

97
## Installation
8+
ZfcAdmin is enabled to be installed via composer. Load `zf-commons/zfc-admin` in your `composer.json` file. You can specify its version (currently only 0.1.0 is recommended) or use `dev-master` to load the latest version from master. Enable ZfcAdmin in your `application.config.php` configuration file.
109

11-
### Main Setup
12-
13-
1. Clone this project into your `./vendor/` directory and enable it in your
14-
`application.config.php` file.
10+
If you do not want to use composer, clone this project (either as a git submodule or not) into `./vendor/` directory.
1511

1612
## Usage
13+
ZfcAdmin allows you to create routes under a single parent "admin" route. You can also use it to enable navigation in your admin layout. Furthermore integration of [BjyAuthorize](https://github.com/bjyoungblood/BjyAuthorize) and [ZfcRbac](https://github.com/spiffyjr/ZfcRbac) is provided.
1714

18-
### Add own Modules to admin path
19-
20-
When creating your own modules you are required to register these with the zfcadmin path as child_routes
21-
22-
In your module.config.php add the route as shown in the example
23-
24-
'router' => array(
25-
'routes' => array(
26-
'zfcadmin' => array(
27-
'child_routes' => array(
28-
'mymodule' => array(
29-
'type' => 'Literal',
30-
'options' => array(
31-
'route' => '/mymodule',
32-
'defaults' => array(
33-
'controller' => 'mycontroller',
34-
'action' => 'index',
35-
),
36-
),
37-
'child_routes' =>array(
38-
'mychildroute' => array(
39-
'type' => 'literal',
40-
'options' => array(
41-
'route' => '/',
42-
'defaults' => array(
43-
'controller' => 'mycontroller',
44-
'action' => 'myaction',
45-
),
46-
),
47-
),
48-
),
49-
),
50-
),
51-
),
52-
),
53-
),
54-
55-
56-
### Add your routes to the Navigation
57-
58-
You can inject your routes from your own modules into the admin navigation as shown below
59-
60-
61-
'navigation' => array(
62-
'admin' => array(
63-
'mynavigation' => array(
64-
'label' => 'My Module',
65-
'route' => 'zfcadmin/myroute',
66-
),
67-
),
68-
),
69-
70-
## Enable Access restriction
71-
72-
Restrict access to unauthorized Users.
73-
74-
### Solution
75-
76-
1. Install BjyAuthorize and enable in you application.config.php
77-
2. Import data/data.sql into your database.
78-
3. Create a user with ZfcUser and set the user_id and role_id in the database
79-
(e.g. user_id = 1, role_id = admin)
80-
81-
## How To override Admin Layout
82-
83-
Override the built in admin layout with your custom layout
84-
85-
### Solution
86-
87-
1. In your module under the `view` directory create the folder `layout`
88-
2. Create the override script `admin.phtml`
89-
90-
## How to override Admin controller view
91-
92-
Override the built in Controller view
93-
94-
### Solution
95-
96-
1. In your module, under the view directory, create the folder tree zfc-admin/admin
97-
2. Create the necessary override view scripts, depending on which page(s) you want to change:
98-
* Default page: zfc-admin/admin/index.phtml
99-
100-
101-
NOTE: Your module must be loaded after ZfcAdmin or the overriding will not work. To do this, place your module after ZfcAdmin in the `modules` key of your application configuration (`config/application.config.php`).
15+
The complete configuration is flexible, so you can update the zfcadmin parent route, its children, the navigation and all default provided view scripts. Read more in the [documentation](docs/1.Introduction.md) about usage and customization of ZfcAdmin.
10216

17+
## Development
18+
ZfcAdmin is currently under development. The authors feel ZfcAdmin is stable enough for production versions and you can always fix your ZfcAdmin version to a specific tag. Feel free to report bugs in the [issue tracker](https://github.com/ZF-Commons/ZfcAdmin/issues) or come by on IRC at the Freenode channel `#zftalk`.

‎docs/1.Introduction.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Introduction
2+
ZfcAdmin is a low-level module that helps Zend Framework 2 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 ZfcAdmin, 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.
3+
4+
Every part of ZfcAdmin is customizable. In the pages listed below futher configuration options are explained. This documentation consists of the following pages:
5+
6+
1. [Introduction](1.Introduction.md)
7+
2. [Routes](2.Routes.md)
8+
3. [Navigation](3.Navigation.md)
9+
4. [Authorization](4.Authorization.md)
10+
5. [Views & Layout](5.ViewLayout.md)

‎docs/2.Routes.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# Routes
2+
ZfcAdmin enables a single route named `zfcadmin`, which is a literal route and standard using the url `/admin`. You can create child routes under `zfcadmin` so you enable urls like `/admin/foo` or `/admin/bar/baz`.
3+
4+
## Add child route
5+
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`:
6+
7+
8+
'router' => array(
9+
'routes' => array(
10+
'zfcadmin' => array(
11+
'child_routes' => array(
12+
'foo' => array(
13+
'type' => 'literal',
14+
'options' => array(
15+
'route' => '/foo',
16+
'defaults' => array(
17+
'controller' => 'MyModule\Controller\MyController',
18+
'action' => 'index',
19+
),
20+
),
21+
),
22+
),
23+
),
24+
),
25+
),
26+
27+
## Change the `/admin` url
28+
If you want your admin interface at `/backend` or something else, you must override the value of the route. In the following condig, the `/admin` route value is replaced with `/backend`. Make sure this is enabled in a config where the module is registered *later* than ZfcAdmin (otherwise, the config will not overwrite ZfcAdmin's configuration):
29+
30+
'router' => array(
31+
'routes' => array(
32+
'zfcadmin' => array(
33+
'options' => array(
34+
'route' => '/backend',
35+
),
36+
),
37+
),
38+
39+
## Change the controller behind `/admin`
40+
By default, the `/admin` url links to the `ZfcAdmin\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 condig, the `zfcadmin` 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 ZfcAdmin (otherwise, the config will not overwrite ZfcAdmin's configuration):
41+
42+
'router' => array(
43+
'routes' => array(
44+
'zfcadmin' => array(
45+
'options' => array(
46+
'defaults' => array(
47+
'controller' => 'MyModule/Controller/AdminController',
48+
'action' => 'dashboard',
49+
),
50+
),
51+
),
52+
),
53+
),
54+
55+
## Link to documentation pages
56+
57+
1. [Introduction](1.Introduction.md)
58+
2. [Routes](2.Routes.md)
59+
3. [Navigation](3.Navigation.md)
60+
4. [Authorization](4.Authorization.md)
61+
5. [Views & Layout](5.ViewLayout.md)

‎docs/3.Navigation.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Navigation
2+
ZfcAdmin allows a dedicated navigation structure for the admin interface. By default, ZfcAdmin initiates a [Twitter Bootstrap](http://twitter.github.com/bootstrap) layout with on top the main admin navigation. These admin buttons are customizable.
3+
4+
## Add a page
5+
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](2.Routes.md) in your child pages of ZfcAdmin and therefore it is straightforward to use the `route` parameter in the navigation configuration.
6+
7+
In the following example, there is a navigation element called "My Module" and points to `zfcadmin/foo/bar` as a route. This page is configured as follows:
8+
9+
'navigation' => array(
10+
'admin' => array(
11+
'my-module' => array(
12+
'label' => 'My Module',
13+
'route' => 'zfcadmin/foo/bar',
14+
),
15+
),
16+
),
17+
18+
The navigation in ZfcAdmin uses `Zend\Navigation` and more information about the configuration of this component is located in the [Zend Framework 2](http://framework.zend.com/manual/2.0/en/modules/zend.navigation.quick-start.html) reference guide.
19+
20+
## Link to documentation pages
21+
22+
1. [Introduction](1.Introduction.md)
23+
2. [Routes](2.Routes.md)
24+
3. [Navigation](3.Navigation.md)
25+
4. [Authorization](4.Authorization.md)
26+
5. [Views & Layout](5.ViewLayout.md)

‎docs/4.Authorization.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Authorization
2+
ZfcAdmin allows authorization via [BjyAuthorize](https://github.com/bjyoungblood/BjyAuthorize) or [ZfcRbac](https://github.com/ZF-Commons/ZfcRbac). Configuration for both modules is provided to easily configure ZfcAdmin. Authorization enables you to restrict access to `/admin` and every other page under ZfcAdmin.
3+
4+
## BjyAuthorize authorization
5+
BjyAuthorize works with `Zend\Permission\Acl` as access restriction component. The BjyAuthorize module combines `Zend\Permission\Acl` with the standard user module [ZfcUser](https://github/com/ZF-Commons/ZfcUser). To enable access restriction with BjyAuthorize, install the module and enable it in your `application.config.php`.
6+
7+
Furthermore, ZfcAdmin has a `zfcadmin.global.php` file in the [config](../config/) directory. Copy this file over to your `config/autoload` directory. It directly provides BjyAuthorize configuration to restrict access to users for the `/admin` route. Only users in the "admin" group are allowed to access ZfcAdmin's pages.
8+
9+
Instructions for further configuration of BjyAuthorize are provided in the [repository of BjyAuthorize](https://github.com/bjyoungblood/BjyAuthorize).
10+
11+
## ZfcRbac authorization
12+
ZfcRbac works with `Zend\Permission\Rbac` as access restriction component. The ZfcRbac module combines `Zend\Permission\Rbac` with the standard user module [ZfcUser](https://github/com/ZF-Commons/ZfcUser). To enable access restriction with ZfcRbac, install the module and enable it in your `application.config.php`.
13+
14+
Furthermore, ZfcAdmin has a `zfcadmin.global.php` file in the [config](../config/) directory. Copy this file over to your `config/autoload` directory. It directly provides ZfcRbac configuration to restrict access to users for the `/admin` route. Only users in the "admin" group are allowed to access ZfcAdmin's pages.
15+
16+
Instructions for further configuration of ZfcRbac are provided in the [repository of ZfcRbac](https://github.com/ZF-Commons/ZfcRbac).
17+
18+
## Link to documentation pages
19+
20+
1. [Introduction](1.Introduction.md)
21+
2. [Routes](2.Routes.md)
22+
3. [Navigation](3.Navigation.md)
23+
4. [Authorization](4.Authorization.md)
24+
5. [Views & Layout](5.ViewLayout.md)

‎docs/5.ViewLayout.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# View and layout scripts
2+
ZfcAdmin includes an admin layout and index view script, so ZfcAdmin 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.
3+
4+
## Override admin layout
5+
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`:
6+
7+
'view_manager' => array(
8+
'template_path_stack' => array(
9+
__DIR__ . '/../view'
10+
),
11+
),
12+
13+
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`.
14+
15+
Make sure MyAdmin is registered in the `application.config.php` and `ZfcAdmin` is located *above* `MyAdmin`. Then your new admin template will be loaded.
16+
17+
## Override admin index view script
18+
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:
19+
20+
'view_manager' => array(
21+
'template_path_stack' => array(
22+
__DIR__ . '/../view'
23+
),
24+
),
25+
26+
Then create the folders `zfc-admin/admin` inside the `view` directory. Inside `zfc-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/zfc-admin/admin/index.phtml`.
27+
28+
Make sure MyAdmin is registered in the `application.config.php` and `ZfcAdmin` is located *above* `MyAdmin`. Then your new index view script will be loaded.
29+
30+
## Rename admin layout
31+
If you already have a `layout/admin` layout template and want to use another layout for ZfcAdmin, you can rename the layout used. By default it is `layout/admin` but you can for example configure ZfcAdmin to switch to `layout/backend`. You can enable this configuration to use another layout name:
32+
33+
'zfcadmin' => array(
34+
'admin_layout_template' => 'layout/backend'
35+
),
36+
37+
## Disable layout
38+
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 ZfcAdmin where you disable the layout. To accomplish this, you must terminate the view model in the controller:
39+
40+
public function indexAction()
41+
{
42+
$model = new ViewModel;
43+
$model->setTerminal(true);
44+
45+
return $model;
46+
}
47+
48+
## Use normal `layout.phtml` layout
49+
You can disable ZfcAdmin 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:
50+
51+
'zfcadmin' => array(
52+
'use_admin_layout' => false
53+
),
54+
55+
## Link to documentation pages
56+
57+
1. [Introduction](1.Introduction.md)
58+
2. [Routes](2.Routes.md)
59+
3. [Navigation](3.Navigation.md)
60+
4. [Authorization](4.Authorization.md)
61+
5. [Views & Layout](5.ViewLayout.md)

0 commit comments

Comments
 (0)