Quick links: Content - sections - sub sections
EN FR
Jelix 1.9.0-dev

Section: master_admin

^ Jelix modules
Switch to language: FR

master_admin is a module providing a web interface dedicated to administration.

Before to custom the user interface, you should create it.

The module contains three zones:

  • admin_menu: a menu system
  • dashboard: a dashboard.
  • admin_infobox: a box which contains informations about the current user

default:index action displays the dashboard.

Activating a module for the admin interface

When you want to use a module, you have to activate it into the modules section of the configuration, but you should also indicate from which entry point it is accessible.

If your admin interface has a specific entry point, like admin.php (by default), and if your module is for the admin interface, you should indicate its urls into the urls.xml, in the section corresponding to the admin.php entry points.

For exemple, here is a basic configuration in the var/config/urls.xml, for an admin interface in which you want to manage users and rights with the jauthdb_admin and jacl2db_admin modules:


 <entrypoint name="admin">
     <url pathinfo="/" module="master_admin" action="default:index" />
     <url module="master_admin"/>
     <url module="jauth"/>
     <url module="jacl2db"/>
     <url module="jauthdb_admin"/>
     <url module="jacl2db_admin"/>

     <!-- here your own admin module -->
     <url module="news_admin" />
 </entrypoint>

Note: you shouldn't have a module that have controllers for the administration interface and controllers for the front web site at the same time. Create two modules for this case. It eases configuration and security.

If you want to use a module for both, the admin interface and the front web site, (like jauth), you must create two applications instead of two entry points.

Using the menu system

The admin_menu zone displays a menu. This menu contains in fact some sub-menus, and sub-menus contain items. Each item and sub-menu has an id.

If you want to add items or sub-menus, you should create an event listener for masteradminGetMenuContent event.

Imagine you have a "news" module, and you want to add a menu item to your CRUD controller to manage news. In the news/events.xml :


<events xmlns="http://jelix.org/ns/events/1.0">
   <listener name="news">
       <event name="masteradminGetMenuContent" />
   </listener>
</events>

And in news/classes/news.listener.php, you should return in the event a masterAdminMenuItem object for each item you want to add:


class newsListener extends jEventListener{

   function onmasteradminGetMenuContent ($event) {
        $event->add(new masterAdminMenuItem('news', "manage news", jUrl::get('news~admin:index'), 30, 'general'));
        $event->add(new masterAdminMenuItem('newscat', "manage news catagories", jUrl::get('news~admincat:index'), 31, 'general'));
        $event->add(new masterAdminMenuItem('newssearch', "search news", jZone::get('news~search'), 32, 'general', 'zone'));
   }
}

Here are parameters for masterAdminMenuItem:

  • an id for the menu item
  • the label of the link
  • the URL of the link
  • the order in the sub-menu
  • the id of the sub-menu where to add the item.

There are four predefined sub-menus:

  • 'toplinks' : links to display at the top of the menu
  • 'system' : the menu "System"
  • 'crud' : the menu "Data management"
  • 'refdata' : the menu "Reference Data"

If you want any HTML content in the menu item instead of a simple link, here are the arguments you should give to masterAdminMenuItem:

  • an id for the menu item
  • an empty string.
  • the HTML content
  • the order in the sub-menu
  • the id of the sub-menu where to add the item. By default, there are two sub-menus: 'toplinks' and 'system'.
  • 'content' (by default, the value is 'url' for a link as content.

You can add new sub-menus. Simply create a masterAdminMenuItem object, where the sub-menu id parameter is empty.

Using the infobox zone

At the top right corner of the user interface of master_admin, there is the zone admin_infobox. This zone displays the name of the user, a link to his profile, and a link to logout. You can add other links or simple content in this zone by responding to the masteradminGetInfoBoxContent event, and then by returning masterAdminMenuItem objects.

For example, let's declaring this event in the file news/events.xml :


<events xmlns="http://jelix.org/ns/events/1.0">
   <listener name="news">
       <event name="masteradminGetMenuContent" />
       <event name="masteradminGetInfoBoxContent" />
   </listener>
</events>

In our class newsListener, let's adding the method onmasteradminGetInfoBoxContent, which will return an item to display a link to a page, which will displays the list of news written by the user.


class newsListener extends jEventListener{
   //....


   function onmasteradminGetInfoBoxContent ($event) {

        $event->add(new masterAdminMenuItem('news', "Your own news", jUrl::get('news~admin:usernews')));
  
   }
}

Using the dashboard

A dashboard is often useful in a web administration. It is often the start page of this kind of application, and displays miscellaneous informations.

Each modules can display informations on the dashboard. They should listen to masterAdminGetDashboardWidget event, and add in the event one or more masterAdminDashboardWidget objects, which declare a "widget" content. This object is very simple, it has three properties: title, content and order.

So, you should provide a title and a html content foreach "information box" you want to add on the dashboard, and the order you want to sort the display.


class newsdashboardListener extends jEventListener {

   function onmasterAdminGetDashboardWidget ($event) {

        $box = new masterAdminDashboardWidget();
        $box->title = "Latest news";
        $box->content = jZone::get("news~latest");
        $box->order = 1;

        $event->add($box);
   }
}

Templates

The module contains two templates:

  • index_login.tpl: displays the login form
  • main.tpl: displays the main web interface.

You should use this templates in your response object.

The init-admin jelix command creates by default two responses object, adminHtmlResponse and adminLoginHtmlResponse in your responses/ directory. This responses use the template of master_admin, and you can of course modify this objects to customize them.