Control Panel Documentation
by Matthew McNaney

The Control Panel module performs two functions. First, it is the
interface for selecting which module you want to access. Second, it is
a tool for developers to create their own control panels within their
module. This document covers the latter.


Quick Tab Setup
------------------------------------------------------------
Your 'tabs' are what allow the user to navigate through your
module. The content contained within the tab (usually a word or set of
words) are links that take the user to another portion of your
module. You should begin by creating these links as follows.

Create an array of tabs. The index of the tab will be the
identifier. The array value is an array as well. The embedded array
describes how it should be displayed.

For example:

// This is the http address to where you want the tab to take the user
$link = "index.php?module=myMod";

// This array contains the content to be displayed in the tab
// (the title) and the link we made above
$command1 = array ("title" => "Main Menu", "link" => $link);
$command2 = array ("title" => "Add New", "link" => $link);

Note: you can also add a "link_title" key and value to this array to
label the link. This information would appear only on mouse-over"

$command1 = array ("title" => "Main Menu", "link" => $link,
                   "link_title"=> "Go to the Main Menu");

// Now we put the title and the link array into the tab array.
// The index of the $tabs array is the identifier. This is what will
// appear in the address field when clicked on

$tabs['main_menu'] = $command1;
$tabs['add_new']   = $command2;

This would create tabs like so:

 ___________   __________
| Main Menu | | Add New  |
---------------------------------

When you click on Main Menu, you would be directed to:

http://www.yourSite.com/index.php?module=myMod&command=main_menu&tab=main_menu

You should also create 'catching code'. This is an if or switch
statement that decides what direction to take the code dependant upon
the tab. For example:

switch ($_GET['tab']){
       case "main_menu":
       $content = MyMod::main_menu();
       break;

       case "add_new":
       $content = MyMod::add_new();
       break;
}

Of course you could use information from the command variable as
well. For example you could have made the $link:

$link = "index.php?module=myMod&command=main_menu";

and then alter the 'catching code' appropiately. In most cases, it is
easier to rely on the tab name however.

Strict mode
------------------------------------------------------------
If you want to add linked tab, but don't want the control panel to
append the tab information to the link, send it in strict mode:

$link = array('title'=>'Special',
              'link' =>'javascript:alert(\'Hello World\')',
              'strict' => true);

$tabs['special'] = $link;


Creating the Panel Object
------------------------------------------------------------
Now you need to create a panel object. First require the Panel.php
class in Control Panel. The easier way to do this is:

PHPWS_Core::initModClass("controlpanel", "Panel.php");

Now construct your panel object.

$panel = & new PHPWS_Panel("myModPanel");

The myModItem designates the 'panel name'. You could have multiple
panels in your module with different names. The panel name allows
Control Panel to keep them separate. Your panel name should not be
identical to your module name.

Setting the Tabs
-------------------------------------------------------------
Put the tabs in the panel like so:

$panel->quickSetTabs($tabs);

Control Panel will keep track of what tab is active. Normally you can
find out which tab is current by checking the $_GET or $_REQUEST variable:

if ($_GET['tab'] == "main_menu")
   $content = MyMod::main_menu_content();

However, the user may arrive at your control panel without the tab
getting listed. In that case you can grab the current tab with the
getCurrentTab function:

$current_tab = $panel->getCurrentTab();

If you want to force a specific tab use setcurrentTab, like so:

$panel->setCurrentTab('main_menu');


Setting the Content
-----------------------------------------------------------
You can see from the examples above that we are piping the results of
the tab choice into a $content variable. We will put that content into
our panel like so:

$panel->setContent($content);


Displaying the Panel
------------------------------------------------------------
Once the tabs and content are set, you are ready to display them.

$finalPanel = $panel->display();

Put that information in Layout and you are done!
Layout::add($finalPanel);


Alternate Display option
------------------------------------------------------------
You can save some steps by displaying the data like so:

Layout::add($panel->display($content, $title, $message));

or to make an embedded tabbed panel:

Layout::add(PHPWS_ControlPanel::display($panel->display($content, $title, $message)));

This way you do not use setContent. Instead you use the
default.tpl template file that comes with the ControlPanel module.


Changing the Look of your Control Panel
-------------------------------------------------------------
Control Panel uses its own templates by default. You can change this
behavior by setting the module and panel template.

$panel->setModule("myModule");
$panel->setPanel("myPanel.tpl");

Control Panel would then look in mod/myModule/templates/myPanel.tpl
for an alternate template file. If you wish to do this, I recommend
you copy the panel.tpl file from the controlpanel/templates/ directory
to get started.


Security
------------------------------------------------------------
By default, panels do not include authorization keys in the link.
If you want it to, call enableSecure();

$panel->enableSecure();


Tips:
Use the 'allow' function in Users to control what tabs can be seen:

$tabs['main_menu'] = $command1;

if ($_SESSION['User']->allow("myMod", "add_new"))
   $tabs['add_new']   = $command2;


You may want to put your content into the Control Panel's main
page. To do so just do the following:

$content = PHPWS_ControlPanel::display($panel->display());
Layout::add($content);

This places your tabs and content into the content of the Control
Panel's content.