Creating custom debug panels - mithra62/ee_debug_toolbar GitHub Wiki

The Debug Toolbar (EEDT) is fully extensible and adding your own debug panels can be done from any ExpressionEngine Add-on Extension. Creating custom Debug Toolbar (EEDT) panels starts with creating an extension that listens for the eedt_add_panel hook. Your extension then simply needs to create an instance of the DebugToolbar\Panels\Model class and customize it to your needs.

A rough outline of the process:

  1. Create an ExpressionEngine extension that hooks into our custom EEDT hooks.
  2. When your extension is called, create an instance of the DebugToolbar\Panels\Model class, customize it to your needs and return it.
  3. That's it!

If you want to provide more advanced functionality, EEDT provides a full PHP and JS API that will not only let you change the look and functionality of your debug panel, but also break out of the "panel" paradigm and create fully featured page widgets.

A few important concepts

Panel output caching By default, the EEDT tries to keep its page footprint as small as possible. As such, any HTML contents you provide for your panel will actually be loaded and inserted into the panel dynamically when a user clicks your panel's toolbar button.

Ajax communication The eedt JS library provides convenience methods for communicating with your PHP scripts. It is important to remember that any performance measurements you make during the AJAX request will be for the wrong page request, since the page load will have already occurred.

Not just panels Although the name might be misleading, if you are looking to create a front end debugging widget that does not conform to the 'panel' paradigm (ie: open/closes on toolbar button click) you still need to create an DebugToolbar\Panels\Model instance. Once instantiated, simply change the panel injection point to be outside the toolbar.

Views Its always important to keep your code organized, so we recommend you use CodeIgniter's view loading system to load your panel contents. In order to have your panel contents loaded within your panel you must return your view as a string, so ensure that when calling the setPanelContents method, you call ExpressionEngine's load->view() method with a third argument of TRUE to indicate to the loader that you want the view returned as a string.

$panel = new Model();
$panel->setPanelContents(ee()->load->view("view_name", [], true);

Create an ExpressionEngine extension

First step is to simply create your panel extension. If unsure, checkout the official ExpressionEngine docs.

The extension hook used when creating the extension is called eedt_add_panel. Your activate extension method could look like this:

<?php
public function activate_extension()
{
    $data = [];

    $data[] = [
        'class' => 'My_custom_panel_ext',
        'method' => 'eedt_add_panel',
        'hook' => 'eedt_add_panel',
        'settings' => '',
        'priority' => 500,
        'version' => $this->version,
        'enabled' => 'y',
    ];

    foreach ($data as $ex) {
        ee()->db->insert('extensions', $ex);
    }
}

In this instance we specified for the hook to call a method called eedt_add_panel. Here is what our method could look like:

<?php
public function eedt_add_panel(array $panels, array $vars)
{
	$panels = (ee()->extensions->last_call != '' ? ee()->extensions->last_call : $panels);
	
        $panels['my_custom_panel'] = new Model();
        $panels['my_custom_panel']->setName("my_custom_panel");
        $panels['my_custom_panel']->setPanelContents(ee()->load->view('my_custom_panel'));
	$panels['my_custom_panel']->setButtonIcon(URL_THIRD_THEMES.'my_custom_panel/images/my_custom_panel.png');
	$panels['my_custom_panel']->setButtonLabel("Toolbar button label");

	return $panels;
}

As you can see, the eedt_add_panel method is called with two arguments. The first argument is the panel array and the second is a collection of toolbar settings and values for use by our panel.

In order to create a panel, we simply need to instantiate a new DebugToolbar\Panels\Model, set some properties such as name, labels etc, add it onto the $panels array and then return it. See The Panel Model for all available methods).

We've also used the ee()->load->view('custom_view', $vars, TRUE) to fetch the panel contents from a PHP view file as a string.

Advanced usage

If your custom panel requires its own JS & CSS files, there are setter methods on the DebugToolbar\Panels\Model that will allow you to specify as many as you want. You can even break out of the 'panel' paradigm (eg: creating a permanent overlay - See the bundled Memory History extension by specifying the panel injection point.

See The Panel Model for full PHP API reference and also the Javascript Reference to learn about the various events and utilities available once your JS has loaded.

<?php
public function eedt_add_panel(array $panels, array $view)
{
	$panels = (ee()->extensions->last_call != '' ? ee()->extensions->last_call : $panels);
	
	$panels['my_custom_panel'] = new Model();
	$panels['my_custom_panel']->setName('my_custom_panel');
	$panels['my_custom_panel']->setButtonLabel("Toolbar button label");
	$panels['my_custom_panel']->setPanelContents(ee()->load->view('custom_view', $vars, TRUE));
        $panels['my_custom_panel']->addJs(URL_THIRD_THEMES . 'my_custom_panel/js/script1.js');
        $panels['my_custom_panel']->addJs(URL_THIRD_THEMES . 'my_custom_panel/js/script2.js');
        $panels['my_custom_panel']->addCss(URL_THIRD_THEMES . 'my_custom_panel/css/styles1.css');
        $panels['my_custom_panel']->addCss(URL_THIRD_THEMES . 'my_custom_panel/css/styles2.css');
        $panels['my_custom_panel']->setInjectionPoint(Model::PANEL_AFTER_TOOLBAR);

	return $panels;
}

Add interactivity with JavaScript

Below is an example of what you could put in your JS file to add a bit of interactivity to various panel events:

eedt.on('my_custom_panel', 'init', function(domNode, panel){
    //Your code for when the panel initialises (ie: toolbar button click)

    //Fetch some data from the server
    eedt.ajax('My_custom_panel_ext', 'my_custom_method', function(data){
        //Code
    });
});

eedt.on('my_custom_panel', 'open', function(domNode, panel){
    //Your code for when the panel opens
});

eedt.on('my_custom_panel', 'close', function(domNode, panel){
    //Your code for when the panel closes
});