Dev:Adding an Admin Page

From Habari Project

Jump to: navigation, search

Plugin authors may want to provide an additional page in the administration interface, and this page will guide you through doing so.

Important note: Do not add an admin page unless it is absolutely necessary. When making such a determination, keep the following factors in mind:

  • The admin menu is designed to be as simple as possible, so you should not clutter it up with unneeded pages.
  • New admin pages should not be used to provide configuration or simple panels for your plugin. For those, simply add a panel to the plugins page.
  • The built-in content type system is extremely powerful and works in a wide variety of situations. Whenever possible, simply create a new content type and modify the admin page as needed.

The following guide steps through the process of creating a new page. If you are savvy, you can simply jump to the example code.

Contents

Determining Access for a Page

The entire admin panel is protected by significant access control lists, which are automatically applied to all administration pages. When determining who can access your admin page, there are two options. The first is to filter based upon an ACL token. The second, which should be used when you want to give all users access, is to implement a custom filter function.

Using an ACL token

To filter based upon an ACL token, you must first know the name of the token you will be checking against. If needed, you should first create a new token. You then add it to the required set of tokens on the page which you are controlling access to.

public function filter_admin_access_tokens( array $require_any, $page )
{
	switch ( $page ) {
		case 'page_name':
			$require_any = array( 'token_name' => true );
			break;
	}
	return $require_any;
}

Using a Custom Filter

If you implement a custom filter, you can do any checks you wish to determine if the user has access to the page. To do so, simply implement the admin_access filter. Whatever you return (true or false) will determine whether the user can access the page. Remember to check that you only apply it to your page!

This code will grant all users access to your page:

public function filter_admin_access( $access, $page, $post_type ) {
	if ( $page != 'page_name') {
		return $access;
	}
 
	return true;
}

Create a Template

You must create a new template for your admin page. In the majority of cases, this template should display the standard admin header and footer. Don't forget to register your new template!

public function action_init()
{
	$this->add_template('templatename', dirname($this->get_file()) . '/template.php');
}

Sample template:

<?php $theme->display('header');?>
 
<div class="container">
	<h2>Heading</h2>
	<p>Hi</p>
</div>
 
<?php $theme->display('footer'); ?>

Handling the Page Action

You must implement two handlers for each page: a post and a get handler. Alternately, you can simply alias one handler to the other.

Handler

Your handler is a simple action, in the form of action_admin_theme_get_pagename, for the GET action on the pagename page. You can do whatever you want in the handler, including displaying the template. Just remember to call exit at the end. Otherwise, 404 output will be created after your page.

A simple handler which outputs your template:

public function action_admin_theme_get_calendar( AdminHandler $handler, Theme $theme )
{
	$theme->display( 'templatename' );
 
	// End everything
	exit;
}

Alias

As noted above, you should expect for both GET and POST requests on your page. However, you can easily alias one of requests to the other using an alias function.

public function alias()
{
	return array(
		'action_admin_theme_post_calendar' => 'action_admin_theme_get_calendar'
	);
}

Adding a Menu Item

To add a menu item, you must implement the adminhandler_post_loadplugins_main_menu filter. Each menu item is represented by an array containing various properties, as you can see in the below code. This code will insert the new menu item before the "groups" item. To change the location, simply change it to a different menu item key.

public function filter_adminhandler_post_loadplugins_main_menu( array $menu )
{
	$item_menu = array( 'pagename' => array(
		'url' => URL::get( 'admin', 'page=pagename'),
		'title' => _t('Page description'),
		'text' => _t('Page Name'),
		'hotkey' => 'J',
		'selected' => false
	) );
 
	$slice_point = array_search( 'groups', array_keys( $menu ) ); // Element will be inserted before "groups"
	$pre_slice = array_slice( $menu, 0, $slice_point);
	$post_slice = array_slice( $menu, $slice_point);
 
	$menu = array_merge( $pre_slice, $item_menu, $post_slice );
 
	return $menu;
}

Example Code

To put it all together, the following code will create a page, determine its access, and add a link to it in the menu.

public function alias()
{
	return array(
		'action_admin_theme_get_pagename' => 'action_admin_theme_post_pagename'
	);
}
 
public function action_init()
{
 
	$this->add_template('templatename', dirname($this->get_file()) . '/templatename.php');
 
}
 
public function filter_admin_access( $access, $page, $post_type ) {
	if ( $page != 'pagename') {
		return $access;
	}
 
	return true;
}
 
public function action_admin_theme_get_pagename( AdminHandler $handler, Theme $theme )
{
	$theme->display( 'templatename' );
 
	// End everything
	exit;
}
 
public function filter_adminhandler_post_loadplugins_main_menu( array $menu )
{
	$item_menu = array( 'pagename' => array(
		'url' => URL::get( 'admin', 'page=pagename'),
		'title' => _t('Page description'),
		'text' => _t('Page Name'),
		'hotkey' => 'J',
		'selected' => false
	) );
 
	$slice_point = array_search( 'groups', array_keys( $menu ) ); // Element will be inserted before "groups"
	$pre_slice = array_slice( $menu, 0, $slice_point);
	$post_slice = array_slice( $menu, $slice_point);
 
	$menu = array_merge( $pre_slice, $item_menu, $post_slice );
 
	return $menu;
}
Other Development Pages · Developer Introduction
Personal tools
This is a cached copy of the requested page, and may not be up to date.

Sorry! This site is experiencing technical difficulties.
Try waiting a few minutes and reloading.

(Cannot contact the database server: Access denied for user 'habari'@'localhost' to database 'habari_wiki' (localhost))


You can try searching via Google in the meantime.
Note that their indexes of our content may be out of date.