Dashboard Modules

From Habari Project

Contents 1 Overview 2 Modules Class 2.1 Modules::add 2.2 Modules::remove 2.3 Modules::remove_by_name 2.4 Modules::set_option 2.5 Modules::get_option 2.6 Modules::get_all 2.7 Modules::get_active 2.8 Modules::set_active 3 Loading Modules 4 Use of the Modules class in a plugin 4.1 Register/unregister modules on activation/deactivation 4.2 Implement filter_dash_module_*

Overview

• Core modules are a plugin which is active by default on install. This plugin creates a default module list if the current module list is empty, this way users don't start out with a blank dash
• A module cannot assume that it is unique. Each instance of a module must be able to have its own set of options. This non-uniqueness should require a minimal amount of work from plugin developers to be compatible with it. Many options will not need this flexibility. For instance, the latest entries module will always show the same entries. However, if this module were extended to display entries by a particular author, or only entries in a particular category... then you might like to have separate instances of this module with different options.

Modules Class

Modules::add

• param modulename

Adds a module to the dashboard. Adds to the dash_modules list in the userinfo table. This function will generate and return a unique moduleID.

Modules::remove

• param id

Removes a module from the dashboard.

Modules::remove_by_name

• param modulename

Removes all dash modules of type modulename.

Modules::set_option

• param moduleID
• param optionname
• param value

Sets a module option

Modules::get_option

• param moduleID
• param optionname

Gets a module option

Modules::get_all

Returns a list of all available modules.

Modules::get_active

Returns a list of modules displayed on the dashboard, sorted by appearance order

Modules::set_active

Sets the list of modules displayed on the dashboard.

Loading Modules

The general order of operations for loading the modules is the following:

1. Get list of modules to load and their associated IDs.

2. Foreach module do:

   1. Get the module fetch function.
   2. Set module theme variables using the module's fetch function.
      Fetch function are of the form func_name( $this->theme, $module_id )
      A module gets its options with Modules::get_option( $module_id, 'option' )
   3. Get the module template.
   4. Fetch module template with $this->fetch( templatename )

Use of the Modules class in a plugin

Register/unregister modules on activation/deactivation

Implement the filter_dash_modules() function to add your module to the list of available modules. You should supply your module template in this call.

function filter_dash_modules( $modules )
{
	$modules[] = 'My Module';
	$this->add_template( 'myplugin_module', dirname( __FILE__ ) . '/my_module.php' );
	return $modules;
}
 
function action_plugin_activation( $file )
{
	if( Plugins::id_from_file($file) == Plugins::id_from_file(__FILE__) ) {
		// automatically add this module to the dash if you want
		// it activated by default.
		Modules::add( 'My Module' );
	}
}
 
function action_plugin_deactivation( $file )
{
	if( Plugins::id_from_file($file) == Plugins::id_from_file(__FILE__) ) {
		// remove the module from the dash if it is active
		Modules::remove_by_name( 'My Module' );
	}
}

Implement filter_dash_module_*

The dashboard looks for a filter matching your module name. It creates the function name using:

$func = 'filter_dash_module_' + Utils::slugify( $module_name, '_' );

So, if you module is named 'An Amazing Module', you need to create a function called filter_dash_module_an_amazing_module().

public function filter_dash_module_my_module ( $module, $module_id, $theme )
{
	// set some theme variables, e.g.
	$theme->comment_count = Comments::get( array( 'count' => 1 ) );
 
	// get module options using $module_id
	if ( Modules::get_option( $module_id, 'yow' ) ) {
	    // get some random something or other
	}
    
	$module['title'] = '<a href="/mylink">My Module</a>'; // title is optional
	$module['content'] = $theme->fetch( 'myplugin_module' );
	
	return $module;
}