Admin Plugin

USE ONLY ON FRESH AKELOS INSTALLATIONS AS IT MIGHT OVERRIDE YOUR EXISTING FILES!!!

If you are using an old version of Akelos, replace it with a new version before installing the Admin Plugin.

The Admin Plugin installer does have code that prevents/controls overwriting of files, but they can be overridden and your files overwritten.

The Admin plugin assists you on creating a basic admin with RBAC (permission, role and user management).
It is not meant to be used as a “fit all” solution but as a simple to adapt/modify base for your applications.
The Admin plugin, like Akelos itself, is based on conventions for building navigation and handling user permissions.
The user permission interface is heavily inspired by the Community plumbing section of Drupal.

  ./script/plugin install admin

You will be prompted for the URL path and master account details.
After installing you can visit http://yourhost.com/admin (by default admin)

You can use the admin scaffold generator exactly like the scaffold generator.

  ./script/generate admin_scaffold

It will generate controllers inside the the admin module, views that match the admin conventions, and helpers with permission check-points in order filter the links to show.

Keeping track of who can do what on your admin is plain and simple. Permissions are grouped/scoped into Extensions for clarity.
You can restrict access to portions of your application using code like

    if(User::can('Create project', 'Project administration')){
      // create project code
    }

In this case, “Create project” is a specific permission and “Project administration” is the group to which “Create project” is defined. See the Permissions page.
This can be added to your models, helpers or controllers if the user has been authenticated.

In your views you can use

    <? if($admin_helper->can('View credit card number', 'Account management')) : ?>
      <p>_{Credit card number}: {card.number} </p>
    <? endif; ?>

The ideal scenario is to have an authenticated area under the admin module and unrestricted areas which do not require credentials under normal controllers.

By default, actions on controllers inside the admin module are added to the Permissions table. In order to disable this behaviour on your controller, just define the attribute

    var $protect_all_actions = false;

and select individual actions, if any, using

    var $protected_actions = 'index,show,edit,delete';

The RBAC system consists of users, roles, permissions and extensions. Users may have one or more roles. Roles may have one or more permissions. Each permission has an extension.

When the plugin is installed, it is installed with the following data:

users -- roles ------------------ permissions ----------------------------------- extension
 
  1       Application Owner   
          Administrator ---|-- add action     ---------------|----------------- Admin::Users
                           |-- destroy action ---------------|
                           |-- edit action    ---------------|
                           |-- index action   ---------------|
                           |-- listing action ---------------|
                           |-- show action ------------------|
                           |-- manage users --------------------------------|-- Admin Menu Tabs
                           |-- Accounts (users controller,   |              |
                           |             listing action) -------------------|
                           \-- Edit other users -------------/              |
                                                                            | 
          Registered User ----|-- Dashboard (dashboard controller) ---------/ 
                              \-- index action -------------------------------- Admin::Dashboard
                                                                                Admin::Permissions
                                                                                Admin::Roles

If you're logged as Root (Application Owner role), new permissions found in your code will be added automatically to your permission pool. Just like with multilingual strings on Akelos.

In order to benefit from the menu building system and automated privileges, your controllers in the admin module must extend AdminController, which is located at

    ./app/controllers/admin_controller.php

There are 2 different menus on the admin:

• An admin menu, which affects the whole admin module.
• A controller menu, which is dependent on each controller.

Menus are built by declaring the following attributes in your controller:

    class Admin_UsersController extends AdminController
    {
        // just for this controller
        var $controller_menu_options = array(
        'Accounts'   => array('id' => 'accounts', 
                              'url'=>array('controller'=>'users', 
                              'action'=>'listing')),
        'Roles'   => array('id' => 'roles', 'url'=>array('controller'=>'roles')),
        'Permissions'   => array('id' => 'permissions', 
                                 'url'=>array('controller'=>'permissions', 'action'=>'manage')),
        );
 
        // Which tab to select on the controller menu
        var $controller_selected_tab = 'Accounts';
    }

The code is quite straight forward.

By convention, the selected tab will be the one that matches the array key with current controller name. In this case we manually set it to Accounts.

By default, strings on the menu system are internationalized.

You could also have set

var $admin_menu_options = array(....);

which would have summed/overridden the options inherited from the AdminController.

To completely override the admin menu you must use

var $_admin_menu_options = array(....);

We are going to add an employees table.

Find this code:

var $_admin_menu_options = array(
    'Dashboard' => array('id' => 'dashboard', 'url'=>array('controller'=>'dashboard'),
        'link_options'=>array(
            'accesskey'=>'h',
            'title' => 'general status and information'
    )),
    'Manage Users' => array('id' => 'users', 'url'=>array('controller'=>'users'), 
        'link_options'=>array(
            'accesskey' => 'u',
            'title' => 'add user, change password, manage user settings'
    ))
    );

Add an entry for the employees table:

var $_admin_menu_options = array(
    'Dashboard' => array('id' => 'dashboard', 'url'=>array('controller'=>'dashboard'),
        'link_options'=>array(
            'accesskey'=>'h',
            'title' => 'general status and information'
    )),
    'Manage Users' => array('id' => 'users', 'url'=>array('controller'=>'users'), 
        'link_options'=>array(
            'accesskey' => 'u',
            'title' => 'add user, change password, manage user settings'
    )),
    'Employee' => array('id' => 'employee', 'url' => array('controller' => 'employee'), 
        'link_options' => array(
            'accesskey' => 'e',
            'title' => 'add and edit employees'
    ))
    );

Note that we put a comma after the “Manage Users” entry, just before the “Employee” entry.

In a terminal window, change to your project's root directory and enter this:

./script/generate model employee

In installers/employee_installer.php, modify the code to define the employees table. Then migrate it:

./script/migrate employee install

./script/generate admin_scaffold employee

With a web browser, log into your project as the Application owner. Create an employee. Click on Manage Users, then Permissions. Then, check the boxes necessary to limit access as you desire. Be careful to examine every occurrence of “employee”. Save the settings.

And you're good to go.

The admin provides a basic user model. It's quite limited on purpose, so you can evolve the basic model to suit your needs.

The Language/Locale Management article shows how to modify an Admin installation so that the pages have a menu of available languages/locales from which the user may select.

This is not a full featured automated admin. You'll have to custom code your intranets, but this might speed up the process.

It is anticipated that Admin may need to be customized. Therefore, when it is installed, files are copied into the project's main directories instead of being referenced in /app/vendor/plugins/Admin.

Plans for the future include:

• Stop adding features :)