Click here to go back to the previous section: Formatters

Please note that this documentation relates to Vanilla 1

The Panel is the sidebar (in the default Vanilla theme) with all of your page-specific options. The Panel control is located in the library/Framework/Framework.Control.Panel.php file, and has a number of different methods which allow you to add content.

If you take a look at any page of Vanilla, the control panel typically contains a heading with links underneath. These separated heading/link groups are referred to as Lists.

In this example, there are two lists: “Discussion filters” and “Searches”.

In order to create a new list, you should call the Panel’s AddList method:

AddList($ListName, $Position = '0', $ForcePosition = '0')

The first parameter is your new list name, the second parameter is an integer value indicating where in the panel your new list should be placed. Any elements placed in the panel are assigned a numeric value like this, and before the panel is rendered, the items are sorted in ascending order. These $Position values tend to be in the three digit range, so that you can easily choose a value between say 100 and 200 to slide your list into. The third parameter is a boolean value indicating if the list should be forced into the position indicated by the $Position parameter. If it is true and there is already an item in the position you’ve chosen, your new list will push the existing list down the page by incrementing it’s own position value by 1.

It is important to note that if you want your extension to be multi-lingual, you will need to create a new library code for your ListName parameter and reference it properly using the Context object’s GetDefinition method. For example, if I wanted to create a new list called “Cool Links”, I add my list like this:

$Panel->AddList($Context->GetDefinition('CoolLinks'));

Then I would open up my language dictionary (languages/YourLanguageName.php) and add the new definition for the “CoolLinks” code:

$Context->Dictionary['CoolLinks'] = 'Cool Links';

At the time of this writing, there is no great method for adding definitions to dictionaries (but who knows what kind of extensions people will come up with - so check out the Add-Ons site). I recommend that any extensions with dictionary codes should simply place their new definitions at the top of their extension file. This way when a translator comes along, they can find the codes within each extension and add them to their own conf/language.php file.

Okay, so now I’ve got my new list name, but I still need some links beneath it. You can add links to a list with the Panel control’s AddListItem method:

AddListItem($ListName, $Item, $Link, $Suffix = '', $LinkAttributes = '', $Position = '0', $ForcePosition = '0');

ListName is, of course, the name of the list that this new link should be placed under. Item is the text to go inside the link, which will typically be grabbed from the language file using the Context object’s GetDefinition method - the same rules apply here about adding to the language dictionary. Link is the actual url where the text should be linked to. Suffix is text to be placed after the link. Position allows you to place your link in a particular position in this list - same rules apply here as the Position variable in the AddList method. LinkAttributes allows you to place anything you want into the anchor tag of the link - this can be used to do things like target=”_blank”.

So, let’s add some cool links to the list:

// Put the ListName into a variable for the sake of brevity
$ListName = $Context->GetDefinition("CoolLinks");
 
// Add a link to google
$Panel->AddListItem($ListName,
   $Context->GetDefinition('Google'),
   'http://www.google.com');
 
// Add a link to Kottke.org
$Panel->AddListItem($ListName,
   $Context->GetDefinition('Kottke'),
   'http://www.kottke.org',
   $Context->GetDefinition('Rock');

Up next I need to add my new definitions to the language dictionary, and then I put it all together and save it as Example/default.php in the extensions directory:

<?php
/*
Extension Name: Example Extension
Extension Url: http://lussumo.com/docs
Description: Adds a list to the control panel
Version: 1.0
Author: Mark O'Sullivan
Author Url: http://markosullivan.ca
*/
 
// Remember to only place your list on the pages you want
if ($Context->SelfUrl == "index.php") {
 
   $Context->Dictionary['CoolLinks'] = 'Cool Links';
   $Context->Dictionary['Google'] = 'Google Search Engine';
   $Context->Dictionary['Kottke'] = "Jason Kottke's Blog";
   $Context->Dictionary['Rock'] = 'ROCK!';
   
   // Put the ListName into a variable for the sake of brevity
   $ListName = $Context->GetDefinition('CoolLinks');
   $Panel->AddList($ListName);
   
   // Add a link to google
   $Panel->AddListItem($ListName,
      $Context->GetDefinition('Google'),
      'http://www.google.com');
      
   // Add a link to Kottke.org (*tip-hat at Kottke for linking us*)
   $Panel->AddListItem($ListName,
      $Context->GetDefinition('Kottke'),
      'http://www.kottke.org',
      $Context->GetDefinition('Rock');
}
?>

Now I can go into the settings tab, “Manage Extensions”, and enable “Example Extension”. Then go back to the index page and check my work:

You’d be pretty limited if all you could do was add link lists to the control panel. There are probably a million things you could think of to add to the panel: everything from advertisements to preference widgets to a mini-search input. The list could go on and on. So, with this in mind we gave you the ability to add any string to the control panel. The string can contain any code you want - plain text or html, it doesn’t matter. It’s a simple matter of calling the Panel’s AddString method:

AddString($String, $Position = '0', $ForcePosition = '0');

String is, of course, the string you want to add to the panel. Position and ForcePosition work as with the other two methods mentioned above. Position is an integer value that places the element in a stack. The stack is sorted in ascending order before it is rendered. So choose an arbitrary number and then increase or decrease it to move it up and down in the panel. ForcePosition will force your string into the chosen Position and move any elements already in that spot down in the panel.

So, let’s take on the “Mini-Search” example. I want to add a mini-search that allows you to search through discussion comments. First I’ll build my string:

$SearchForm = '<div class="PanelSearch">
<form method="get" action="search.php">
<input type="hidden" name="PostBackAction" value="Search" />
<input type="hidden" name="Type" value="Comments" />
<input type="text" name="Keywords" class="PanelInput" />
<input type="submit" class="PanelSearchButton" value="'.$Context->GetDefinition('Search').'" />
</div>';

Now I need to add my string to the panel:

$Panel->AddString($SearchForm);

I’m also going to create a new css file to handle my new cascading stylesheet definitions: PanelSearch, PanelInput, and PanelSearchButton

I can add my stylesheet with the following code:

$Head->AddStyleSheet("extensions/PanelSearch/style.css", "screen");

That’s it. So, make a new PanelSearch/default.php file in the extensions directory:

<?php
/*
Extension Name: Panel Search
Extension Url: http://lussumo.com/docs
Description: Adds a mini, comment-search form to the control panel
Version: 1.0
Author: Mark O'Sullivan
Author Url: http://markosullivan.ca
*/
 
// Remember to only place your list on the pages you want
if ($Context->SelfUrl == "index.php") {
 
   $Context->Dictionary['Search'] = 'Search';
   
   // Create my search form
   $SearchForm = '<div class="PanelSearch">
   <form method="get" action="search.php">
   <input type="hidden" name="PostBackAction" value="Search" />
   <input type="hidden" name="Type" value="Comments" />
   <input type="text" name="Keywords" class="PanelInput" />
   <input type="submit" class="PanelSearchButton" value="'.$Context->GetDefinition('Search').'" />
   </div>';
 
   // Add the form to the panel
   $Panel->AddString($SearchForm);
   
   // Add the style to the head
   $Head->AddStyleSheet("extensions/PanelSearch/style.css", "screen");
}
?>

Now let’s go enable it and check our work:

Click here to read the next section on developing new extensions: Adding User Preferences