AddonSDK

From WoWRosterWiKi
(Difference between revisions)
Jump to: navigation, search
Line 4: Line 4:
  
 
==WoWRoster v2.0.0b AddOn Development==
 
==WoWRoster v2.0.0b AddOn Development==
−
Updated: 19:13, 25 August 2007 (PDT)
+
15:07, 25 October 2007 (PDT)
  
 
This document is being revised as 2.0 goes through development<br>
 
This document is being revised as 2.0 goes through development<br>
Line 10: Line 10:
  
 
==Changes==
 
==Changes==
 +
* [[User:Zanix|Zanix]] 15:07, 25 October 2007 (PDT)
 +
** 2 new installer menu functions
 +
** Install::add_menu_pane()
 +
** Install::remove_menu_pane()
 +
*** Details on these new functions can be found under "8.5 Creating/Editing Menu Entries"
 +
** Install::add_menu_button() has an additional parameter $section
 +
*** This allows you to add a menu button to a custom made menu pane
 +
** Install::create_table() now adds the table name to the drop list
 +
*** This means that when the addon has an error on installation, these tables will also be dropped
 +
 
* [[User:Zanix|Zanix]] 09:55, 2 October 2007 (PDT)
 
* [[User:Zanix|Zanix]] 09:55, 2 October 2007 (PDT)
 
** Updated templating to allow template files to be in addons/addonname/templates/
 
** Updated templating to allow template files to be in addons/addonname/templates/
Line 21: Line 31:
  
 
* [[User:Zanix|Zanix]] 20:33, 25 September 2007 (PDT)
 
* [[User:Zanix|Zanix]] 20:33, 25 September 2007 (PDT)
−
** Install::add_table() should be Install:create_table()
+
** Install::add_table() should be Install::create_table()
  
 
* [[User:Zanix|Zanix]] 09:34, 25 September 2007 (PDT)
 
* [[User:Zanix|Zanix]] 09:34, 25 September 2007 (PDT)
Line 452: Line 462:
 
*: Add a table to the Roster database
 
*: Add a table to the Roster database
 
*: This is the preferred method for adding a table to the Roster database as it adds the correct charset for you
 
*: This is the preferred method for adding a table to the Roster database as it adds the correct charset for you
 +
*: This also adds the table to the drop list for rollback, which is important when an install fails
  
 
* <span style="color:maroon;">$installer</span>->drop_table(<span style="color:maroon;">$tablename</span>);
 
* <span style="color:maroon;">$installer</span>->drop_table(<span style="color:maroon;">$tablename</span>);
Line 485: Line 496:
  
 
===Creating/Editing Menu Entries===
 
===Creating/Editing Menu Entries===
−
There are 3 separate functions for this.<br>
+
There are 5 functions for creating, changing, and editing menu entries.<br>
−
Note the title should be unique per AddOn.
+
Note the menu button titles should be unique per AddOn.<br>
 +
Using your basename in the key will work fine.
 +
 
 +
* <span style="color:maroon;">$installer</span>->add_menu_pane(<span style="color:maroon;">$name</span>)
 +
*: Adds a menu pane to insert menu entries into
 +
*: The addon's basename is prefixed to this section name
 +
*:: If you set the name to 'panel' and your addon's basename is something, then the section name will be entered as 'something_panel'
 +
*:: This is to reduce the chance that an addon will overwrite another addon's custom pane
 +
 
 +
* <span style="color:maroon;">$installer</span>->remove_menu_pane(<span style="color:maroon;">$name</span>)
 +
*: Removes a menu pane
 +
*: The addon's basename is prefixed to this section name
 +
*:: If you set the name to 'panel' and your addon's basename is something, then the section name will be 'something_panel'
 +
*:: This is to reduce the chance that an addon will remove another addon's custom pane
  
−
* <span style="color:maroon;">$installer</span>->add_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
+
* <span style="color:maroon;">$installer</span>->add_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>, <span style="color:maroon;">$section</span>)
 
*: Adds a menu button. Parameters:
 
*: Adds a menu button. Parameters:
 
*: <span style="color:maroon;">$title</span>
 
*: <span style="color:maroon;">$title</span>
Line 502: Line 526:
 
*:: To use and image in your AddOns images/ folder, specify the image with the extension 'icon.png'
 
*:: To use and image in your AddOns images/ folder, specify the image with the extension 'icon.png'
 
*:: DO NOT use a full path to the image, just the filename.
 
*:: DO NOT use a full path to the image, just the filename.
 +
*: <span style="color:maroon;">$section</span>
 +
*:: Pick which menu pane to add the button to.
 +
*:: Useful for adding buttons to a custom pane.
 +
*:: You can only change the section to a custom made section
 +
*::: For example, you cannot add a char scope button to the guild scope
  
 
* <span style="color:maroon;">$installer</span>->update_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
 
* <span style="color:maroon;">$installer</span>->update_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)

Revision as of 22:07, 25 October 2007

WR.net

Important note: When you edit this page, you agree to release your contribution into the public domain.
If you do not want this or can not do this because of license restrictions, please do not edit.

Geographylogo.png Languages: 

English

Main Page

Contents


WoWRoster v2.0.0b AddOn Development

15:07, 25 October 2007 (PDT)

This document is being revised as 2.0 goes through development
Keep checking back for changes and additions

Changes


Info and Download

You can view the open source project at http://www.wowroster.net

For corrections and/or suggestions - http://www.wowroster.net


Thanks to: http://www.wowroster.com
And Everyone involved in the project.


Download the Roster AddOnSDK

Info.png Note: Download not yet updated for Roster 2.0



Certified WoWRoster AddOn

Certified WoWRoster AddOn

AddOns that conform to our Coding Standards and the basic outline described within this document, will be given a "AddOn Framework Standards Compliant" stamp of approval.


Requirements for Approval


Basics of an AddOn

The following are required to run the WoWRoster back-end and to be able to run any AddOns
>Roster Requirements<

The AddOn system is designed so that you can mod the roster base without having to change the base code as it could change a lot between versions.
Hopefully with this system we will be closer to having a drop-in module system without having to mod a lot of the base files each time.

We will be constantly refining the system as we go along.
So with each new version of Roster, some AddOns may break (not work in the new WoWRoster)

Tools clipart.png Important:

DO NOT use php short tags in your php files
This is also stated in the WoWRoster Coding Standards
NO! <?  ?>
YES <?php  ?>
NO! <?=$var; ?>
YES <?php echo $var; ?>
Use the "long tags" as the short ones can break web servers with short_tags set to "off"


Changes Since 1.7.3


AddOn Framework

Features

  1. Uses output buffering, which means all the output is stored in a variable that is sent to the browser
  2. Do not have to include Roster's conf.php
  3. Do not have to include/declare $roster object
  4. Do not have to connect to Roster's database
  5. Do not have to include your inc/conf.php
  6. AddOn files: inc/conf.php, style.css, inc/update_hook.php, and locale files are OPTIONAL!
    Even additional locale files are optional, enUS.php is the default locale, and is required if you have locale files


What it does

  1. Includes all Roster config variables for you to use ($roster->config)
  2. Includes all Roster SQL functions for your use ($roster->db)
  3. Includes all Roster and AddOn language variables for you ($roster->locale->wordings, $roster->locale->act)
  4. Includes all Roster css styles
  5. The Roster header, footer, and menu are included to your files.
    These can be disabled if needed, more below...

Best of all, this is transparent to you!


AddOn Directory Structure

Here is an example of an AddOn's directory structure 

roster/
|_ addons/
   |_ addonname/
      |_ admin/
      |  |_ index.php
      |  |_ other.php
      |
      |_ char/
      |  |_ index.php
      |  |_ other.php
      |
      |_ guild/
      |  |_ index.php
      |  |_ other.php
      |
      |_ inc/
      |  |_ conf.php
      |  |_ functions.php
      |  |_ install.def.php
      |  |_ search.inc
      |  |_ update_hook.php
      |
      |_ locale/
      |  |_ deDE.php
      |  |_ enUS.php
      |  |_ esES.php
      |  |_ frFR.php
      |
      |_ realm/
      |  |_ index.php
      |  |_ other.php
      |
      |_ index.php
      |_ somefile.php
      |_ style.css
      |_ util.php


admin Folder

The admin folder houses files for the Roster CP
Normally you'll never need files here because the Config API can handle most configuration needs

If you do need a custom config interface, this is where you make it

Info.png Note: The File parameter is optional

This will normally grab your AddOn's config data from the 'roster_addon_config' table in the database and display the options using the Config API

If you need your own file, you need only to place index.php in addons/addonname/admin/

You can also have the best of both worlds
For example, the Members List and Character Info AddOns use both the Config API and custom files


char Folder

Files for use in the Character scope
Data for the requested character is passed to the AddOn
If member= is not specified or if this member does not exist, an error message will display

member= can be either the member id number, or name@realm text

Accessing other files in the char scope is easy
addons/addonname/addonname/char/file.php is accessed like this:


guild Folder

Files for use in the Guild scope
Data for the requested guild is passed to the AddOn
If guild= is not specified, the default guild/realm name set in Roster CP will show
If the guild does not exist or if there is no data for this guild, an error message will display

guild= can be either the guild id number, or name@realm text

Accessing other files in the guild scope is easy
addons/addonname/guild/file.php is accessed like this:


inc Folder

This folder houses special files not meant for direct access by the AddOn Framework
These files are conf.php, install.def.php, search.inc, and update_hook.php
You can also use this folder for lib, library, and/or functions files

Place any files here that you do not or should not be accessed directly by the AddOn Framework


locale Folder

Where locale translation files go
See below for more info Locale Files


realm Folder

Files for use in the Realm scope
Data for the requested realm is passed to the AddOn
If realm= is not specified, the default realm name set in Roster CP will show
If the realm does not exist or if there is no data for this realm, an error message will display

realm= can be text

Accessing other files in the realm scope is easy
addons/addonname/realm/file.php is accessed like this:


Other Files and the util Scope

Files not in these folders are considered under the util scope
This scope is not restricted if there is no guild or character information and can be accessed before data is in the database

Accessing other files in the util scope is easy
addons/addonname/file.php is accessed like this:


Required Files

There are a few files that you must have


Linking to AddOns

You can link to any file in the root AddOn folder

The url to access each page is simple

Info.png Note: "file" is optional

The values explained


Creating the Installer

This installer requires a similar install file definition as DragonFly CMS, with some important exceptions:

You should create a file called inc/install.def.php with in it a class that is named identical to your AddOn's install directory name.
This name will be referred to as your AddOn's basename.


Properties

$credits = array(
	array(	"name"=>	"Name",
		"info"=>	"Some Info"),
	array(	"name"=>	"Another Name",
		"info"=>	"More Info"),
);


AddOn Install Class Methods


Queries

Queries are added to the install using the $installer methods.


RosterCP API Entries

These entries can be used to build a config page through Roster's config page API


Creating/Editing Menu Entries

There are 5 functions for creating, changing, and editing menu entries.
Note the menu button titles should be unique per AddOn.
Using your basename in the key will work fine.


Other Installer Methods


Example File

Here is an example of an AddOn install file
This shows most of the methods that can be used in an installer

You can find more examples in the addons/ folder in roster 

<?php
/**
 * WoWRoster.net WoWRoster
 *
 * LICENSE: Licensed under the Creative Commons
 *          "Attribution-NonCommercial-ShareAlike 2.5" license
 *
 * @copyright  2002-2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
 * @version    SVN: $Id: install.def.php 897 2007-05-06 00:35:11Z Zanix $
 * @link       http://www.wowroster.net
 * @package    SomeAddon
 * @subpackage Installer
*/
 
if ( !defined('IN_ROSTER') )
{
    exit('Detected invalid access to this file!');
}
 
/**
 * Installer SomeAddon
 *
 * @package    InstanceKeys
 * @subpackage Installer
 */
class SomeAddon
{
	var $active = true;
	var $icon = 'inv_misc_key_06';
 
	var $version = '2.0.0.0';
 
	var $fullname = 'some_addon';
	var $description = 'some_addon_desc';
	var $credits = array(
	array(	"name"=>	"WoWRoster Dev Team",
			"info"=>	"Original Author")
	);
 
 
	/**
	 * Install Function
	 *
	 * @return bool
	 */
	function install()
	{
		global $installer;
 
		// Master and menu entries
		$installer->add_config("'1','startpage','keys_conf','display','master'");
		$installer->add_config("'110','some_addon_conf',NULL,'blockframe','menu'");
 
		$installer->add_config("'1010','colorcmp','#00ff00','color','some_addon_conf'");
		$installer->add_config("'1020','colorcur','#ffd700','color','some_addon_conf'");
		$installer->add_config("'1030','colorno','#ff0000','color','some_addon_conf'");
 
		$installer->add_menu_button('some_addon','guild','','spell_holy_prayerofspirit');
		$installer->add_menu_button('some_addon','guild','log','inv_misc_symbolofkings_01');
 
		$installer->create_table($installer->table('some_table'),"
			`member_id` int(11)    unsigned NOT NULL default '0',
			`row_id`   int(11)    unsigned NOT NULL default '0',
			`type`  tinyint(3) unsigned NOT NULL default '0',
			PRIMARY KEY (`member_id`)");
 
		return true;
	}
 
	/**
	 * Upgrade Function
	 *
	 * @param string $oldversion
	 * @return bool
	 */
	function upgrade($oldversion)
	{
		global installer;
 
		if( version_compare('2.0.0.0', $oldversion,'>') == true )
		{
			// Upgrade versions lower than 2.0.0.0
		}
 
		if( version_compare('2.0.6.4', $oldversion,'>') == true )
		{
			// Upgrade versions lower than 2.0.6.4
		}
 
		if( version_compare('3.0.0.0', $oldversion,'>') == true )
		{
			// Upgrade versions lower than 3.0.0.0
		}
 
		return true;
	}
 
	/**
	 * Un-Install Function
	 *
	 * @return bool
	 */
	function uninstall()
	{
		global $installer;
 
		$installer->remove_all_config();
 
		$installer->drop_table($installer->table('some_table'));
 
		$installer->remove_all_menu_button();
		return true;
	}
}


Creating the Search Class

Properties


Example File

Here is an example of an AddOn search.inc file
From the "News" AddOn which creates the search class and adds the addon into
Rosters Search Engine

You can find more examples in the addons/ folder in roster 

<?php
 
class news_search
{
	var $options;
	var $result = array();
	var $result_count = 0;
	var $link_next;
	var $link_prev;
	var $data = array();	// Addon data
 
 
	function search( $search , $url_search , $limit=10 , $page=0 )
	{
		global $roster;
 
		$first = $page*$limit;
 
		$q = "SELECT `news`.`news_id`, `news`.`author`, `news`.`title`, `news`.`content`, `news`.`html`, "
			. "DATE_FORMAT(  DATE_ADD(`news`.`date`, INTERVAL " 
                        . $roster->config['localtimeoffset'] . " HOUR ), '" . $roster->locale->act['timeformat'] . "' ) AS 'date_format', "
			. "COUNT(`comments`.`comment_id`) comm_count "
			. "FROM `" . $roster->db->table('news','news') . "` news "
			. "LEFT JOIN `" . $roster->db->table('comments','news') . "` comments USING (`news_id`) "
			. "WHERE `news`.`news_id` LIKE '%$search%' "
			. "OR `news`.`author` LIKE '%$search%' "
			. "OR `news`.`date` LIKE '%$search%' "
			. "OR `news`.`title` LIKE '%$search%' "
			. "OR `news`.`content` LIKE '%$search%' "
			. "GROUP BY `news`.`news_id` "
			. "LIMIT $first," . ($limit+1) .";";
 
		$result = $roster->db->query($q);
		$nrows = $roster->db->num_rows($result);
 
		$x = ($limit > $nrows) ? $nrows : $limit;
		if( $nrows > 0 )
		{
			while( $x > 0 )
			{
				list($news_id, $author, $title, $content, $html, $date, $comments) = $roster->db->fetch($result);
 
				$item['author'] = $author;
				$item['date'] = $date;
				$item['title'] = $title;
				$item['url'] = makelink('util-news-comment&amp;id=' . $news_id);
 
				if( $html == '1' && $this->data['config']['news_html'] >= 0 )
				{
					$content = $content;
				}
				else
				{
					$content = htmlentities($content);
				}
				$content = nl2br($content);
 
				$array = explode(' ',$content,101);
				if( isset($array[100]) )
				{
					unset($array[100]);
					$item['more_text'] = true;
				}
				else
				{
					$item['more_text'] = false;
				}
				$item['short_text'] = implode(' ',$array);
 
				$item['footer'] = ($comments == 0?'No':$comments) . ' comment' . ($comments == 1?'':'s');
 
				$this->add_result($item);
				unset($item);
				$x--;
			}
		}
 
		if( $page > 0 )
		{
			$this->link_prev = '<a href="' . makelink('search&amp;page=' . ($page-1) . '&amp;search=' . $url_search . '&amp;s_addon=' 
. $this->data['basename']) . '"><strong>' . $roster->locale->act['search_previous_matches'] . $this->data['basename'] . '</strong></a>';
		}
		if( $nrows > $limit )
		{
			$this->link_next = '<a href="' . makelink('search&amp;page=' . ($page+1) . '&amp;search=' . $url_search . '&amp;s_addon=' 
. $this->data['basename']) . '"><strong> ' . $roster->locale->act['search_next_matches'] . $this->data['basename'] . '</strong></a>';
		}
	}
 
	function add_result( $resultarray )
	{
		$this->result[$this->result_count++] = $resultarray;
	}
}


Roster Config API

This is the current functionality of the Roster Config API.
There are two classes of form types:

Items of the page, pageframe, and pagehide class contain option blocks.
Items of the blockframe or blockhide class contain options.


Menu Bar Items

Usage

In most cases the config_name is a reference to an entry in your locale file. Each entry you make needs to have a unique config name. The entry in the locale file needs to contain at least the prompt text, but can also contain hover help text by seperating them with a vertical bar '|'.

Options Blocks


Options


AddOn Config Function File

addons/addonname/admin/config.func.php


Locale Files

These are used in translating any text in your AddOn if you want to support multi-langages.
As you can see in the example below, we have a file for deDE which is the German language, enUS which is the English language, frFR for French, and esES for Spanish.

Roster currently supports deDE, enUS, frFR, and esES, these are taken out of character profiler based on what region of WOW they are using.

The folder structure for locale files is as follows: 

roster/
|_ addons/
   |_ addonname/
      |_ locale/
         |_ deDE.php
         |_ enUS.php
         |_ esES.php
         |_ frFR.php

When using locale files, it is absolutely necessary to ALWAYS have enUS.php
The AddOn Framework will default to this file if a locale is not found for a specific locale

Example:


Using Locale Strings

When using these them in your script you can use something similar to this 

$header_title = $roster->locale->wordings['locale_key']['some_key'];

or 

$header_title = $roster->locale->act['some_key'];

The first example is to get a specific locale value
The second is a reference to the current locale set in Roster

Remember that Roster's locale files are already added, so you only have to add the stuff that is custom to your AddOn.

So if you need to check to make sure we have don't already have a translation, you can open the files in the "localization/" directory to see the default words that you don't have to duplicate.

Duplication may cause errors in the main Roster code, if you duplicate a main Roster locale variable, you will incur the wrath of the WoWRoster.net Dev Team


Example File

Example from the PvPLog Roster AddOn
addons/pvplog/locale/deDE.php 

<?php
/**
 * WoWRoster.net WoWRoster
 *
 * LICENSE: Licensed under the Creative Commons
 *          "Attribution-NonCommercial-ShareAlike 2.5" license
 *
 * @copyright  2002-2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
 * @version    SVN: $Id: deDE.php 899 2007-05-06 10:16:36Z Zanix $
 * @link       http://www.wowroster.net
*/
 
$lang['bglog']='BG &Uuml;bersicht';
$lang['pvplog']='PvP &Uuml;bersicht';
$lang['duellog']='Duell &Uuml;bersicht';
$lang['duelsummary']='Duell Summary';
 
$lang['totalwins']='Gewinne total';
$lang['totallosses']='Verluste total';
$lang['totaloverall']='Gesamt';
$lang['win_average']='Durchschnittliche Level Differenz (Gewinne)';
$lang['loss_average']='Durchschnittliche Level Differenz  (Verluste)';
 
// These need to be EXACTLY what PvPLog stores them as
$lang['alterac_valley']='Alteractal';
$lang['arathi_basin']='Arathibecken';
$lang['warsong_gulch']='Kriegshymnenschlucht';
 
$lang['world_pvp']='Welt-PvP';
$lang['versus_guilds']='Gegengilden';
$lang['versus_players']='Gegenspieler';
$lang['bestsub']='Beste Subzone';
$lang['worstsub']='Schlechteste Subzone';
$lang['killedmost']='Am meisten get&ouml;tet';
$lang['killedmostby']='Am meisten get&ouml;tet durch';
$lang['gkilledmost']='Am meisten get&ouml;tete Spieler der Gilde';
$lang['gkilledmostby']='Am meister get&ouml;tet durch Spieler der Gilde';
 
$lang['wins']='Gewinne';
$lang['losses']='Verluste';
$lang['overall']='Gesamt';
$lang['best_zone']='Beste Zone';
$lang['worst_zone']='Schlechteste Zone';
$lang['most_killed']='Meisten get&ouml;tet';
$lang['most_killed_by']='Meisten get&ouml;tet durch';
$lang['leveldiff']='LevelDiff';
$lang['bg']='Schlachtfeld';
$lang['kills']='Kills';
 
// guildpvp strings
$lang['guildwins'] = 'Wins by Guild';
$lang['guildlosses'] = 'Losses by Guild';
$lang['enemywins'] = 'Wins by Enemy';
$lang['enemylosses'] = 'Losses by Enemy';
$lang['purgewins'] = 'Guild Member Kills';
$lang['purgelosses'] = 'Guild Member Deaths';
$lang['purgeavewins'] = 'Best Win/Level-Diff Average';
$lang['purgeavelosses'] = 'Best Loss/Level-Diff Average';
$lang['pvpratio'] = 'Solo Win/Loss Ratios';
$lang['playerinfo'] = 'Player Info';
$lang['kill_lost_hist']='Kill/Loss history for %1$s (%2$s %3$s) of %4$s';
$lang['kill_lost_hist_guild'] = 'Kill/Loss history for Guild &quot;%1$s&quot;';
$lang['solo_win_loss'] = 'Solo Win/Loss Ratios (Level differences -7 to +7 counted)';
$lang['guildinfo'] = 'Guild Info';
 
$lang['admin']['pvpconfig'] = "PvPLog Config|Configure PvPLog main options";
$lang['admin']['minPvPLogver'] = "Min PvPLog version|Minimum PvPLog Version zum Upload";


CSS Styles

CSS style from the MembersList AddOn
addons/memberslist/style.css 

/**
 * WoWRoster.net WoWRoster
 *
 * LICENSE: Licensed under the Creative Commons
 *          "Attribution-NonCommercial-ShareAlike 2.5" license
 *
 * @copyright  2002-2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
 * @version    SVN: $Id: style.css 942 2007-05-20 04:50:02Z Zanix $
 * @link       http://www.wowroster.net
 * @package    MembersList
*/
 
.membersRowColor1 {
	background-color:#1F1E1D;
}
 
.membersRowColor2 {
	background-color:#2E2D2B;
}
 
.membersRowAltColor1 {
	background-color:#1F1E3D;
}
 
.membersRowAltColor2 {
	background-color:#2E2D4B;
}

I assume you know what css is...


Template Parser

Available to AddOns is the template parser which enables making the layout of your AddOn easier and easier to edit.
Roster automatically includes the template parser on initialization.

The templates have {CONTAINERS} for the information from php. This {INFO} is replaced by the output of the php code.
This means you have full control of where these containers are displayed or whether they are at all.

Currently the only AddOn in the Roster core that uses templates is "News".
All examples below are from the "News" AddOn.


Getting Started

Create a folder in roster/templates/default/ with your AddOn's basename
Or create a templates/ folder in your addon folder
This folder will hold all the templates for your AddOn


The PHP Side

In your php files, we will be calling the $roster->tpl object to insert data into your template 

// Assign template vars
$roster->tpl->assign_vars(array(
	'L_POSTEDBY' => $roster->locale->act['posted_by'],
	'L_EDIT'     => $roster->locale->act['edit'],
	'L_ADD_NEWS' => $roster->locale->act['add_news'],
 
	'U_ADD_NEWS'  => makelink('util-news-add'),
	'S_ADD_NEWS' => true,
	)
);

or 

$roster->tpl->assign_var('VAR_NAME','value');

What happens here is that we are making and setting template variables.
Notice how the variables in available to the template are much simpler than the php variables
'L_POSTEDBY' as opposed to $roster->locale->act['posted_by']


This all all fine and good for variables, but what if you want a repeating section?
This is quite easy actually.

Here we will be reading from the database and creating a template block variable 

while( $news = $roster->db->fetch($result) )
{
	$roster->tpl->assign_block_vars('news_row', array(
		'TITLE'         => $news['title'],
		'ID'            => $news['news_id'],
		'CONTENT'       => $news['content'],
		'COMMENT_COUNT' => $news['comm_count'],
		'AUTHOR'        => $news['author'],
		'DATE'          => $news['date_format'],
 
		'U_BORDER_S' => border('sorange','start',$news['title'],'60%'),
		'U_BORDER_E' => border('sorange','end'),
		'U_COMMENT'  => makelink('util-news-comment&amp;id=' . $news['news_id']),
		'U_EDIT'     => makelink('util-news-edit&amp;id=' . $news['news_id']),
 
		'L_COMMENT' => ($news['comm_count'] != 1 ?
			sprintf($roster->locale->act['n_comments'],$news['comm_count']) :
			sprintf($roster->locale->act['n_comment'],$news['comm_count'])),
		)
	);
}

This is very useful for tables with repeating rows.

Now we want to select the template we want to display. 

$roster->tpl->set_filenames(array('body' => $addon['basename'] . '/news.html'));
$roster->tpl->display('body');

What happens here is we are assigning a 'handle' to a template file
Then we use that handle to display and output the template

You can assign multiple templates, then display them 

$roster->tpl->set_filenames(array(
	'newshead' => $addon['basename'] . '/news_head.html',
	'body' => $addon['basename'] . '/news.html',
	'newsfooter' => $addon['basename'] . '/news_head.html'
	)
);
$roster->tpl->display('newshead');
$roster->tpl->display('body');
$roster->tpl->display('newsfooter ');

Or in the template file, you can include a template file 

<!-- INCLUDE news/news_head.html -->

(This is an html comment that the parser picks up, then includes this template)


The Template Side

Now we are ready to make the template
This example is from the "News" AddOn

roster/templates/default/news/news.html
or
roster/addons/news/templates/news.html 

<!-- INCLUDE news/news_head.html -->

<!-- BEGIN news_row -->

{news_row.U_BORDER_S}

{news_row.CONTENT}
<hr />
<div style="text-align:left;">
	<span style="float:right;">
	<a href="{news_row.U_COMMENT}">{news_row.L_COMMENT}</a> | <a href="{news_row.U_EDIT}">{L_EDIT}</a></span>
	{L_POSTEDBY}: {news_row.AUTHOR} - {news_row.DATE}
</div>

{news_row.U_BORDER_E}
<br />
<!-- END news_row -->

<!-- IF S_ADD_NEWS --><!-- INCLUDE news/news_foot.html --><!-- ENDIF -->

See how all the variables are here, but wrapped in braces? { }
These are the variables you assigned in the php file

Notice the 'BEGIN news_row'?
This is the beginning of our repeating section 

	$roster->tpl->assign_block_vars('news_row', array(
		'TITLE'         => $news['title'],
		'ID'            => $news['news_id'],

The variables 'TITLE' and 'ID' are available in this loop by appending the loop name 'news_row' and a period to the variable 

	<a href="{news_row.U_COMMENT}">{news_row.L_COMMENT}</a> | <a href="{news_row.U_EDIT}">{L_EDIT}</a></span>

We will try to add more about templates, if anyone finds a good resource for phpbb, eqdkp, or DF templates, let us know...


AddOn Update Hook

The update hook is a file that ties into the lua upload process
You can specify any additional lua files you may you need

There are a few hook modes that an AddOn can make use of


Properties

The following variables are required in the update hook class


Methods

	function addonUpdate($data)
	{
		$this->data = $data;
	}

The following methods are reserved for update hooks
Descriptions for these methods are above and are not required

These function fairly simmilar

You can add other methods or properties as you wish, but be warned that Roster may implement more update hook methods in future versions


Example Update Hook File

This is an example update hook file
Look at memberslist and pvplog (example of additional lua file upload and processing) for more complex examples 

<?php
/**
 * WoWRoster.net WoWRoster
 *
 * LICENSE: Licensed under the Creative Commons
 *          "Attribution-NonCommercial-ShareAlike 2.5" license
 *
 * @copyright  2002-2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
 * @version    SVN: $Id: update_hook.php 899 2007-05-06 10:16:36Z Zanix $
 * @link       http://www.wowroster.net
 * @package    AddOnName
*/
 
if ( !defined('IN_ROSTER') )
{
    exit('Detected invalid access to this file!');
}
 
/**
 * Addon Update class
 * This MUST be the same name as the addon basename
 */
class addonUpdate
{
	var $messages = '';	// Update messages
	var $data = array();	// Addon config data automatically pulled from the addon_config table
	var $files = array();
 
 
	/**
	 * Class instantiation
	 * The name of this function MUST be the same name as the class name
	 *
	 * @param array $data	| Addon data
	 * @return recipe
	 */
	function addonUpdate($data)
	{
		$this->data = $data;
	}
 
	/**
	 * Resets addon messages
	 */
	function reset_messages()
	{
		$this->messages = '';
	}
 
 
	function update()
	{
		global $roster;
 
		$this->messages .= "<span class=\"green\">This is a non CP hook</span><br />\n";
 
		return true;
	}
 
	function guild_pre( $data )
	{
		global $roster;
 
		$this->messages .= "<span class=\"green\">This is a guild_pre hook</span><br />\n";
 
		return true;
	}
 
	function guild( $data , $memberid )
	{
		global $roster;
 
		$this->messages .= "<span class=\"yellow\">This is a guild hook</span><br />\n";
 
		return true;
	}
 
	function guild_post( $data )
	{
		global $roster;
 
		$this->messages .= "<span class=\"red\">This is a guild_post hook</span><br />\n";
 
		return true;
	}
 
	function char_pre( $data )
	{
		global $roster;
 
		$this->messages .= "<span class=\"green\">This is a char_pre hook</span><br />\n";
 
		return true;
 
	}
 
	function char( $data , $memberid )
	{
		global $roster;
 
		$this->messages .= "<span class=\"yellow\">This is a char hook</span><br />\n";
 
		return true;
	}
 
	function char_post( $data )
	{
		global $roster;
 
		$this->messages .= "<span class=\"red\">This is a char_post hook</span><br />\n";
 
		return true;
	}
}


Variables and Functions for AddOns

There are many variables, functions, and classes available for Addons to use


Variables

This is a list of variables that are available for your Addons

All variables are available whether during update hooks or in the framework


Variable Calls

These are added to index.php for some additional support

If you add these into index.php you can turn off the header, footer and menu on the page, by default these are always on. 

$roster->output['show_header'] = false;  // Turn off roster header
$roster->output['show_menu'] = false;    // Turn off roster menu
$roster->output['show_footer'] = false;  // Turn off roster footer

$roster->output['show_menu'] can accept a string or an array of button listings to display
When building an addon, you can build your own button listing that only displays on your addon pages
Pass a string for only one set of buttons, or pass an array for multiple sets of buttons 

$roster->output['show_menu'] = 'main';  // Display the main button listing
$roster->output['show_menu'] = array('main','char');  // Display the main and char button listing 

$roster->output['html_head'] = 'string';

Accepts any string needing to be in the html header for your addon, such as javascript inclusion
roster_header.tpl will pick this variable up and place its contents in the header 

$roster->output['body_attr'] = 'string';

Accepts any string needing to be in the <body> tag in roster_header.tpl 

$roster->output['body_onload'] = 'string';

Accepts any string needing to be in <body onload=""> in roster_header.tpl


Any output needed, just print or echo it
Roster uses php's output buffering to capture all print or echo commands
Then it echos the output where needed


Functions

This is a list of functions that are available for your Addons 

/**
 * Starts or ends fancy bodering containers
 *
 * @param string $style What bordering style to use
 * @param string $mode ( start | end )
 * @param string $header_text Place text in a styled header
 * @param string $hwidth Set a fixed width for the box
 * @return string
 */
function border( $style , $mode , $header_text=null , $width='' )

/**
* Highlight certain keywords in a SQL query
*
* @param string $sql Query string
* @return string Highlighted string
*/
function sql_highlight( $sql )

/**
 * Clean replacement for die(), outputs a message with debugging info if needed and ends output
 *
 * @param string $text Text to display on error page
 * @param string $title Title to place on web page
 * @param string $file Filename to display
 * @param string $line Line in file to display
 * @param string $sql Any SQL text to display
 */
function die_quietly( $text='', $title='', $file='', $line='', $sql='' )

/**
 * Draw a message box with the specified border color, then die cleanly
 *
 * @param string $message | The message to display inside the box
 * @param string $title | The box title (default = 'Message')
 * @param string $style | The border style (default = sred)
 */
function roster_die( $message , $title = 'Message' , $style = 'sred' )

/**
 * This will remove HTML tags, javascript sections and white space
 * It will also convert some common HTML entities to their text equivalent
 *
 * @param string $file
 */
function stripAllHtml($string)

/**
 * This will check if the given Filename is an image
 *
 * @param imagefile $file
 * @return mixed The extentsion if the filetype is an image, false if it is not
 */
function check_if_image( $imagefilename )

/**
 * Recursively escape $array
 *
 * @param array $array The array to escape
 * @return array The same array, escaped
 */
function escape_array( $array )

/**
 * Recursively stripslash $array
 *
 * @param array $array
 *	The array to escape
 * @return array
 *	The same array, escaped
 */
function stripslash_array( $array )

/**
 * Converts a datetime field into a readable date
 *
 * @param string $datetime datetime field data in DB
 * @param string $offset Offset in hours to calcuate time returned
 * @return string formatted date string
 */
function readbleDate( $datetime , $offset=null )

/**
 * Gets a file's extention passed as a string
 *
 * @param string $filename
 * @return string
 */
function get_file_ext( $filename )

/**
 * Converts seconds to a string delimited by time values
 * Will show d,h,m,s
 *
 * @param string $seconds
 * @return string
 */
function seconds_to_time( $seconds )

/**
 * Check to see if an addon is active or not
 *
 * @param string $name | Addon basename
 * @return bool
 */
function active_addon( $name )

/**
 * Handles retrieving the contents of a URL trying multiple methods
 * Current methods are curl, file_get_contents, fsockopen and will try each in that order
 *
 * @param string $url	| URL to retrieve
 * @param int $timeout	| Timeout for curl
 * @param  string $user_agent	| Useragent to use for connection
 * @return mixed		| False on error, contents on success
 */
function urlgrabber( $url , $timeout = 5 , $user_agent=false )

/**
 * Debugging function dumps arrays/object formatted
 *
 * @param array $arr
 * @param int $tab
 * @return string
 */
function aprint( $arr , $prefix='' )

/**
 * Helper function that returns the localized gem color in english
 *
 * @param string $socket_color
 * @return string $color
 */
function socketColorEn( $socket_color, $locale )

/**
 * Attempts to write a file to the file system
 *
 * @param string $filename
 * @param string $content
 * @param string $mode
 * @return bool
 */
function file_writer( $filename , &$content , $mode='wb' )


Roster Authorization

Like those nifty log-in boxes in Roster CP?
Now you can easily add one to your addon!

This checks if the user has admin access 

// ----[ Check log-in ]-------------------------------------
$roster_login = new RosterLogin();
 
// Disallow viewing of the page
if( $roster_login->getAuthorized() < 3 )
{
	include_once (ROSTER_BASE . 'roster_header.tpl');
	$roster_menu = new RosterMenu;
	print $roster_menu->makeMenu('main');
 
	print
	'<span class="title_text">Some Title</span><br />'.
	$roster_login->getMessage().
	$roster_login->getLoginForm();
 
	include_once (ROSTER_BASE . 'roster_footer.tpl');
	exit();
}
else
{
	// continue with addon processing
}
// ----[ End Check log-in ]---------------------------------


Addon Credits

Link = http://[www.someurl.net]/roster/?p=credits (SEO: http://[www.someurl.net]/roster/credits.html)
To get credits on the main credit page, set the $credits array in the AddOn's inc/install.def.php file 

var $credits = array(
	array(	"name"=>	"Author Name",
		"info"=>	"Extra Info"),
);

Replace the following

(Use <br> for line breaks)

You can add multiple arrays inside the main one to add more credits
(Try not to add too many, we don't wanna clutter the credits page now do we?)


Tooltips

/**
 * Makes a tootip and places it into the tooltip array
 *
 * @param string $var
 * @param string $content
 */
function setTooltip( $var , $content )

Creates a js variable for use with overlib
Instead of outputting text in the html, you can create a js variable that holds this instead 

/**
 * Easy all in one function to make overlib tooltips
 * Creates a string for insertion into any html tag that has "onmouseover" and "onmouseout" events
 *
 * @param string $tooltip | Tooltip as a string (delimited by "\n" character)
 * @param string $caption | (optional) Text to set as a true OverLib caption
 * @param string $caption_color | (optional) Color for the caption
 * Default is 'ffffff' - white
 * @param bool $mode| (optional) Options 0=colorize,1=clean,2=pass through
 * Default 0 (colorize)
 * @param string $locale | Locale so color parser can work correctly
 * Only needed when $colorize is true
 * Default is $roster_conf['roster_lang']
 * @param string $extra_parameters | (optional) Extra OverLib parameters you wish to pass
 * @return unknown
 */
function makeOverlib( $tooltip , $caption='' , $caption_color='' , $mode=0 , $locale='' , $extra_parameters='' )

Returns this string for use in any html tag that supports onmouseover and onmouseout events 

onmouseover="return overlib(overlib_'.$num_of_tips.$caption.$extra_parameters.');" onmouseout="return nd();"

For more info about makeOverlib() and its supporting functions, look at functions.lib.php


Message Boxes

Functions to draw message boxes 

/**
 * Draw a message box with the specified border color.
 *
 * @param string $message | The message to display inside the box
 * @param string $title | The box title
 * @param string $style | The border style
 * @param string $width | Set a fixed width
 * @return string $html | The HTML for the messagebox
 */
function messagebox( $message , $title='Message' , $style='sgray' , $width='' )

/**
 * Draw a 300x550px scrolling messagebox with the specified border color.
 *
 * @param string $message | The message to display inside the box
 * @param string $title | The box title
 * @param string $style | The border style
 * @param string $width | Initial width with unit
 * @param string $height | Initial height with unit
 * @return string $html | The HTML for the messagebox
 */
function scrollbox($message, $title = 'Message', $style = 'sgray', $width = '550px', $height = '300px')

/**
 * Draw a message box with the specified border color.
 *
 * @param string $message | The message to display inside the box
 * @param string $title | The box title
 * @param string $style | The border style
 * @param boolean $open | True if initially open
 * @param string $width | Initial width with unit
 * @return string $html | The HTML for the messagebox
 */
function messageboxtoggle($message, $title = 'Message', $style = 'sgray', $open = false, $width = '550px')

/**
 * Draw a 300x550px scrolling messagebox with the specified border color.
 *
 * @param string $messages | The message to display inside the box
 * @param string $title | The box title
 * @param string $style | The border style
 * @param string $width | Initial width with unit
 * @param string $height | Initial height with unit
 * @return string $html | The HTML for the messagebox
 */
function scrollboxtoggle($message, $title = 'Message', $style = 'sgray', $open = false, $width = '550px', $height = '300px')
Retrieved from "http://www.wowroster.net/MediaWiki/AddonSDK"
Personal tools
Namespaces
Variants
Actions
WoWRoster
Navigation
Toolbox