Welcome Welcome Guest! Please Register or Login

Search Wiki

User Info

Welcome Anonymous

Membership:

Latest: lawrence

New Today: 4

New Yesterday: 9

Overall: 28629

People Online:

Members: 3

Visitors: 19

Bots: 7

Staff: 0

Staff Online:

No staff members are online!

Main Menu

Home

News

Stories Archive

Newsletters

Topics

Donate

Community

Forums

Downloads

Documentation (Wiki)

IRCChat

WebSVN

Projects

WoWRoster

UniAdmin

Codename-R3

Members options

My Account

Search

Forums

Web

Resource Links

Statistics

AddonSDK

Views

AddonSDK

From WoWRosterWiKi

Jump to: navigation, search

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

Languages:

English

Main Page

java UniUploader

PHP UniUploader

UniAdmin

WoWAddons

WoWRoster v2.0.0 AddOn Development

Updated: 18:18, 15 June 2008 (CDT)

Changes

See Discussion

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

Note:

Download not yet updated for Roster 2.0

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

Unique locale variables
- Use Roster base locale strings whenever possible
- Don't overwrite existing locale strings
  Roster has some protection against this, but AddOns can still overwrite other AddOns' strings
Create AddOns with SQL Debug Output, Debug Mode, and SQL Window enabled in RosterCP
- Even though php notices and warnings are suppressed when these are off, it is good practice to enable these options when coding AddOns
No funky text (such as BOM characters)
(ie: strange characters appearing on top of the roster's menu)
Valid XHTML 1.0 Transitional - http://validator.w3.org
Proper use of the DB layer - $roster->db
Roster main files are not edited
Roster main database tables are not edited, unless you provide a clean way to revert the data in your uninstall

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)

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

All AddOns need to be installed using an install definition file inc/install.def.php.
During install, database tables, graphical configuration, menu buttons, and update hooks can be registered with the main framework.
menu.php file is no longer required.
conf.php is still used because there may be more to initialize than just settings.
- conf.php has been moved to addonname/inc/conf.php
Several variables, most notably $addonDir, have changed names.
localization.php is no longer used.
- Locale files are now placed in the addonname/locale/ folder and are named for the locale they define
Configuration from database is automatically added. Addons are initialized in this order:
- Addon registration record
- Other constants (locations of addon files and the addon base dir)
- Database configuration, if it exists
- Localization files
  - The addon framework uses the $roster->mulitlanguages array to automatically add the default Roster locales
- inc/conf.php file
The addon is called differently now.
- Details are below.
Additional lua files for upload can be specified in the update_hook file of each addon
- Add lua file names in the $files array in the update hook class
- The Roster updater automatically parses any uploaded lua files
  - The file names given to the $files array must be lower case
  - The data is available in the $update->uploadData['luafilename'] array
You do not know the basename at design time.
- Please use the $addon['basename'] variable for this at all times.
On lua updates, the addon's inc/update_hook.php is included once.
- Details for the new update hook structure is below
Menu buttons are created in the database using installer functions
New libraries available:
- lib/install.lib.php: AddOn install/upgrade/uninstall class
- lib/config.lib.php: AddOn config class
- lib/roster.php: Roster global class
  - This holds all of roster's config, locale strings, error control, some output variables, and the db layer
- lib/minixml.lib.php: A XML parser and maker
- lib/xmlparse.class.php: A lightweight XML reader, for parsing large XML files
- lib/template.php
  - Template parser based on DragonFly

AddOn Framework

Features

Uses output buffering, which means all the output is stored in a variable that is sent to the browser
Do not have to include Roster's conf.php
Do not have to include/declare $roster object
Do not have to connect to Roster's database
Do not have to include your inc/conf.php
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

Includes all Roster config variables for you to use ($roster->config)
Includes all Roster SQL functions for your use ($roster->db)
Includes all Roster and AddOn language variables for you ($roster->locale->wordings, $roster->locale->act)
Includes all Roster css styles
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

Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-addonname-file
SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/addonname/file.html

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

Members List uses addons/memberslist/admin/update.php to process data for alt relations
Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-memberslist-update
SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/memberslist/update.html
Character Info uses addons/info/admin/display.php to control data display for each character
Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-info-display
SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/info/display.html

char Folder (character scope)

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

a=c: can be either the member id number, or name@rc-realm text

Note:

'rc' is the Region Code for US or EU realms

Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&a=c:##
Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&a=c:name@rc-realm
SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/a=c:##.html
SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/a=c:name@rc-realm.html

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

Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname-file&a=c:##
SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/file/a=c:##.html

guild Folder (guild scope)

Files for use in the Guild scope
Data for the requested guild is passed to the AddOn
If a=g: 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

a=g: can be either the guild id number, or name@rc-realm text

Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&a=g:##
Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&a=g:name@rc-realm
SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/a=g:##.html
SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/a=g:name@rc-realm.html

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

Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname-file&a=g:##
SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/file/a=g:##.html

inc Folder

This folder houses special files not meant for direct access by the AddOn Framework

conf.php - This is included before any other addon file, any initialization can be done here
install.def.php - The AddOn's install/upgrade/uninstall definition file
search.inc.php - Search plug-in for the Roster search page
update_hook.php - Update Hook file

You can also use this folder for library, class, and/or function 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 (realm scope)

Files for use in the Realm scope
Data for the requested realm is passed to the AddOn
If a=r: 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

a=r: can be text

Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&a=r:rc-name
SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/a=r:rc-name.html

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

Normal Link - http://[www.someurl.net]/roster/trunk/?p=realm-addonname-file&a=r:rc-name
SEO Link - http://[www.someurl.net]/roster/trunk/realm/addonname/file/a=r:rc-name.html

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

Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname
Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname
SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname.html
SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname.html

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

Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname-file
SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname/file.html

Other Files

index.php - The main file for the util scope
style.css - A custom css style for the AddOn

Required Files

There are a few files that you must have

addons/addoname/inc/install.def.php (AddOn install/upgrade/uninstall file)

Linking to AddOns

You can link to any file in the root AddOn folder

The url to access each page is simple

Normal Link - http://[www.someurl.net]/roster/?p=scope-addonname-file
SEO Link - http://[www.someurl.net]/roster/scope/addonname/file.html

Note:

"file" is optional

The values explained

scope - One of five values; realm, guild, char, util
Realm (realm) - Page that uses realm information (a=r:rc-name is appended to the url)
Guild (guild) - Page that uses guild information (a=g:## or a=g:name@server is appended to the url)
Character (char) - Page that uses character information (a=c:## or a=c:name@server must be appended to the url)
Utility (util) - Page that doesn't use either, or could use either, most of the Roster pages are utility type pages (rostercp, update, credits, search)
addonname - The name of the AddOn you are accessing
file - The file you are accessing
If 'file' does not exist, the AddOn Framework defaults the file to index.php

Creating the Installer

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

SQL entries are the same as as passing it to mysql_query() using $installer->add_query($sqlstring)
No rollback data per query. Instead, call $installer->add_backup($table_name) for each table you want restored in case of an upgrade/uninstall failure.
Any backup tables you create are automatically deleted in rollback.
Different required variables to be set.

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, plus Install.

Note:

If your AddOn folder name is 'addon', then the install class would be named 'addonInstall'

The folder name will be referred to as your AddOn's basename.

Properties

var $active
Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.

var $version
String, the current version of your AddOn.
Needs to be compatible with php's version_compare().
Should be incremented on every update. So you know what version someone is running.

var $icon
String, an icon to display for your AddOn in the AddOn management page in RosterCP
Valid icons are from the Interface ImagePack or images in addons/ADDONNAME/images/
To use an Interface icon, specify the image without the extension 'ability_cheapshot'
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.

var $fullname
String, the full name of the AddOn for display.
This can either be literal or reference a locale key.

var $description
String, a sort description of your AddOn.
This can either be literal or reference a locale key.

var $wrnet_id
int, the download ID for this addon on WoWRoster.net
This is used for update checking via wowroster.net for your addon
When your addon is updated in the downloads section, Roster will notify everyone that has your addon installed that a new version is available
For example SigGen is downloaded at http://www.wowroster.net/Downloads/details/id=20.html
20 is SigGen's ID and would be entered here
Roster checks the local addon version to the version field for this addon on wowroster.net

Note:

The downside to entering this info is that when you first submit your addon to the downloads section, you will not know the ID

var $credits
Credits information.

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

AddOn Install Class Methods

install()
Here you can add all queries for a fresh install.
No parameters.
Return true on success, false on failure.

upgrade($oldversion)
Here you can add all queries for an upgrade.
$oldversion, the version you are upgrading from.

Return true on success, false on failure.

uninstall()
Here you should add all queries for an uninstall.
No parameters.
Return true on success, false on failure

Queries

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

$installer->create_table($tablename,$tabledata);
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 also adds the table to the drop list for rollback, which is important when an install fails

$installer->drop_table($tablename);
Drop a table from the Roster database
This isn't required for dropping a table, but it sure is handy

$installer->add_query($sqlstring);
Any valid SQL query

$installer->add_backup($table)
Makes a temporary copy of a table and its contents that is put back in case of a rollback

$installer->add_drop($table)
Have a table be dropped on rollback

RosterCP API Entries

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

$installer->add_config($sqlstring);
Add config sql to `roster_addon_config` table
Format is "'id','config_name','config_value','form_type','config_type'"

$installer->update_config($id, $sqlstring);
Modify an existing config value
$id is the id of the config value
$sqlstring is what would be inside "UPDATE `roster_addon_config` SET $sqlstring WHERE `config_id` = '$id';"
$installer->remove_config($id);
Remove an existing config value
$id is the id of the config value

$installer->remove_all_config();
Removes all the config data for the addon

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.

$installer->add_menu_pane($name)
Adds a menu pane to insert menu entries into
Try to keep this unique to your addon, try using your addon name as part of the name
To label the Panel, add a locale key 'menupanel_PANELNAME'
When adding buttons to a custom pane, Roster ignores the scope and basename parameters of the buttons
Make sure the url is correct when placing buttons in a custom panel

$installer->remove_menu_pane($name)
Removes a menu pane
you cannot remove a roster made pane ('util','realm','guild','char')

$installer->add_menu_button($title, $scope, $url, $icon)
Adds a menu button. Parameters:
$title
The localization key for the menu button's title.

$scope
The scope of the link ('util','realm','guild','char')

$url
The url parameters this button should call the AddOn with

$icon
An icon to display in the button
Valid icons are from the Interface ImagePack or images in addons/ADDONNAME/images/
To use an Interface icon, specify the image without the extension 'ability_cheapshot'
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.

$installer->update_menu_button($title, $scope, $url, $icon)
Changes menu button. Parameters:
$title
The localization key for the menu button's title.

$scope
The scope of the link ('util','realm','guild','char')

$url
The url parameters this button should call the AddOn with

$icon
An icon to display in the button
Valid icons are from the Interface ImagePack or images in addons/ADDONNAME/images/
To use an Interface icon, specify the image without the extension 'ability_cheapshot'
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.

$installer->remove_menu_button($title)
Removes a menu button. Parameters:
$title
The localization key for the menu button's title.

$installer->remove_all_menu_button()
Removes all the menu buttons for the addon.

Other Installer Methods

$installer->table($table, $backup=false)
Returns a full table name from base table name for the current addon and config profile.
If the roster table prefix is 'roster_', and the addon is named 'news', and the table name is 'category'
The table name returned would be 'roster_addons_news_category'

$installer->seterrors($string)
Set an error message to be displayed.

$installer->setmessages($string)
Set a message to be displayed.

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 SomeAddonInstall
{
	var $active = true;
	var $icon = 'inv_misc_key_06';
 
	var $version = '2.0.0.0';
	var $wrnet_id = 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

Get customizable search results on the Roster search page for your AddOn
AddOn search classes are basically just SQL statements with some added functionality for the Search Framework
The search class can search by using SQL and process the data in a readable format for display
The search framework handles pagination, display, and basic form generation (each AddOn can specify additional form fields for its search)

Addon Class

Each AddOn utilizes a hook file /inc/search.inc.php to include a customized search for that AddOn

Properties

var $options
array - Used to to add advanced options to the search page

var $result
array - Search array

var $result_count
int - Counter for results display

var $start_search
int - Time search starts

var $stop_search
int - Time search stops

var $time_search
int - Time spent on search

var $open_table
string - Insert a custom header in the search results

var $close_table
string - Insert a custom footer in the search results

var $search_url
string - Additional data to insert into the prev/next url links

var $data
array - An array that holds all of the addons data, including config
The search framework automatically populates this property

Methods

Constructor

Used to set up data needed for your search class

Use this to populate $this->open_table, $this->close_table, and/or $this->options

search

search( $search , $limit=10 , $page=0 )
The meat and potatoes of your search class
Perform the SQL and process any returned data in this class method

add_result

add_result( $resultarray )
Required function for any search hook used to add result data to the search framework

Return Data

This data is returned to the search framework after your search hook is done processing data
This data must be passed to $this->add_result($item); to show up on the search results page

var $item['results_header']
string - Adds a header before the result row (outside the <tr>) within that addon search

var $item['results_footer']
string - Adds a footer after the result row (outside the </tr>) within that addon search

var $item['html']
string - Allows you to display your own formated HTML code which overrides any predefined search display

Note:

The following variables are only displayed when $item['html'] is not set

var $item['header']
Adds a header before the result cell (inside the <tr><td>) within that addon search

var $item['author']
string - Used to display the author of a post/update/upload

var $item['date']
string - var that will print the date

var $item['url']
string - Variable used to create a makelink() to the results addons home page

var $item['title']
string - Displays the title of the addon

var $item['short_text']
string - Short description of the result

var $item['more_text']
string - Secondary link per result

var $item['footer']
Adds a footer after the result cell (inside the </td></tr>) within that addon search

Search Framework Variables

var $page
int - Counter for page number

var $limit
int - Counter for the number of results that can be displayed per page

var $query
string - Search string passed

var $url_query
string - Urlencoded $query

Example File

Here is an example of an AddOn search.inc file
From the "News" AddOn

You can find more examples in other AddOns such as memberslist or news

<?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: search.inc.php 1664 2008-02-14 04:24:52Z Zanix $
 * @link       http://www.wowroster.net
 * @package    News
 * @subpackage Search
*/
 
if( !defined('IN_ROSTER') )
{
    exit('Detected invalid access to this file!');
}
 
/**
 * News Search
 *
 * @package    News
 * @subpackage Search
 */
class newsSearch
{
	var $options;
	var $result = array();
	var $result_count = 0;
	var $start_search;
	var $stop_search;
	var $time_search;
	var $open_table;
	var $close_table;
	var $search_url;
	var $data = array();    // Addon data
 
	function search( $search , $limit=10 , $page=0 )
	{
		global $roster;
 
		$first = $page*$limit;
 
		$sql = "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 > 0 ? " LIMIT $first," . $limit : '' ) . ';';
 
		//calculating the search time
		$this->start_search = format_microtime();
 
		$result = $roster->db->query($sql);
 
		$this->stop_search = format_microtime();
		$this->time_search = $this->stop_search - $this->start_search;
 
		$nrows = $roster->db->num_rows($result);
 
		$x = ($limit > $nrows) ? $nrows : ($limit > 0 ? $limit : $nrows);
		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--;
			}
		}
		$roster->db->free_result($result);
	}
 
	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:

Option blocks for layout
Actual options

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

Menu Bar Items

display:
Sets the first page that will be displayed when you first select the addon for configuration.
$installer->add_config("'1','startpage','config_name','display','master'")

page, pageframe, pagehide, blockframe, blockhide:
A page of options that gets selected with javascript
$installer->add_config("'110','config_name',NULL,'blockframe','menu'")
$installer->add_config("'150', 'config_name2', NULL, 'page{1', 'menu'")

link
An external link to be opened in the same window
$installer->add_config("120,'config_name','link_value','link','menu'")

newlink
An external link to be opened in a new window
$installer->add_config("170,'config_name','http://www.someurl.com','newlink','menu'")

makelink
Passes this through Roster's makelink() function to generate a correct link to another page in Roster.
$installer->add_config("120,'config_name','link_value','makelink','menu'")

makenewlink
Same as makelink(), except it opens a new browser window.
$installer->add_config("180,'config_name','link_value','makenewlink','menu'")

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

page{n
n columns of options blocks
$installer->add_config("'4001', 'menu_conf_wide', NULL, 'page{2', 'menu_conf'")

pageframe{n
n columns of options blocks in a border
$installer->add_config("'4025', 'menu_conf_left', NULL, 'pageframe{3', 'menu_conf'")

pagehide{n
n columns of options blocks in a border, with a show/hide option
$installer->add_config("'4020', 'menu_conf_hidden', NULL, 'pagehide{1', 'menu_conf'")

blockframe
A list of options in a border
$installer->add_config("'4000, 'menu_conf_top', NULL, 'blockframe', 'menu_conf'")

blockhide
A list of options in a border, with a show/hide option
$installer->add_config("'4050, 'menu_conf_bottom', NULL, 'blockhide', 'menu_conf'")

function{name
Calls the function called name with no parameters to produce the HTML for the page.
If this is a tab (directly linked from the switch menu on the left side) it is put outside the main form so you can put forms in it.
$installer->add_config("'4470', 'menu_conf_right', NULL, 'function{newForm', 'menu_conf_top'")

Options

text{n|m
A text box m characters wide, maximum of n characters input
$installer->add_config("'1110','page_size','0','text{4|30','menu_conf_top'")

radio{op1^val1|op2^val2|op3^val3...
A list of radio buttons with labels op1, op2, op3,...
Which produce values val1, val2, val3,...
Labels are literal, not localization keys.
$installer->add_config("'1010','nojs','0','radio{Server^1|Client^0','menu_conf_top'")

select{op1^val1|op2^val2|op3^val3...
A dropdown box with options op1, op2, op3,...
Which produce values val1, val2, val3,...
Labels are literal, not localization keys.
$installer->add_config("'1020','def_sort','Note','select{Public Note^Note|Officer Note^OfficerNote','menu_conf_top'")

function{name
Calls the function called name with the option record as parameter to produce the HTML for the option.
$installer->add_config("'4270', 'left_text', 'VERANDA.TTF', 'function{fontFiles', 'menu_conf_top'")

display
Displays the option's setting.
$installer->add_config("'3, 'help_text', 'This is to help', 'display', 'menu_conf_top'")

color
Enables the use of the color picker javascript to pick a color from a pallet
$installer->add_config("'4230', 'menu_left_barcolor', '#3e0000', 'color', 'menu_conf_top'")

AddOn Config Function File

addons/addonname/admin/config.func.php

Both function types call functions that can be defined in a file called 'config.func.php' in your AddOn's admin/ directory.
If this file has a function named topBox(), the html returned by this function will be put above the options in the middle column.

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:

You make an AddOn and only create it in English (enUS.php only, no other locale files)
Someone downloads your AddOn for a deDE Roster
The AddOn Framework automatically inserts the enUS locale strings into the deDE locale
This way, you only need to have enUS.php
Later, if other locales are translated, they can be placed into the locale folder and Roster will detect them based on the locales set in localization/languages.php

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'];

$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 MembersList Roster AddOn
addons/memberslist/locale/deDE.php

Note:

This is only part of the file

<?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 1523 2007-12-13 12:24:31Z pleegwat $
 * @link       http://www.wowroster.net
 * @package    MembersList
 * @subpackage Locale
*/
 
// -[ deDE Localization ]-
 
// Installer names
$lang['memberslist']            = 'Mitgliederliste';
$lang['memberslist_desc']       = 'Eine sortier- und filterbare Mitgliederliste';
 
// Button names
$lang['memberslist_Members']	= 'Mitglieder|Zeigt die Gildenmitgliederliste mit Spielernotizen, Zuletzt online, usw... an';
$lang['memberslist_Stats']		= 'Grundwerte|Zeigt die Grundwerte jedes Gildenmitglieds wie Intelligenz, Ausdauer, usw... an';
$lang['memberslist_Honor']		= 'Ehre|Zeigt die PvP-Informationen jedes Gildenmitglieds an';
$lang['memberslist_Log']		= 'Mitglieder Log|Zeigt das upload log fÃ¼r neue und entfernte Mitglieder an';
$lang['memberslist_Realm']		= 'Mitglieder|Zeigt die Mitgliederliste fÃ¼r alle Gilden auf allen Servern an';
$lang['memberslist_RealmGuild']	= 'Gilden|Zeigt eine Liste fÃ¼r alle Gilden auf allen Realms an';
 
// Interface wordings
$lang['memberssortfilter']		= 'Sortierreihenfolge und Filterung';
$lang['memberssort']			= 'Sortierung';
$lang['memberscolshow']			= 'Zeige/Verstecke Spalten';
$lang['membersfilter']			= 'Zeilenfilter';
 
$lang['openall']                = 'Ã–ffne alle';
$lang['closeall']               = 'SchlieÃŸe alle';
$lang['ungroupalts']            = 'Twinkgruppen auflÃ¶sen';
$lang['openalts']               = 'Gruppiere Twinks (Open)';
$lang['closealts']              = 'Gruppiere Twinks (Closed)';
$lang['clientsort']             = 'Clientsortierung';
$lang['serversort']             = 'Serversortierung';
 
// Column headers
$lang['onote']                  = 'Offizier Notiz';
 
$lang['honorpoints']            = 'Ehrenpunkte';
$lang['arenapoints']            = 'Arenapunkte';
 
$lang['main_name']              = 'Hauptcharaktername';
$lang['alt_type']               = 'Alt type';
 
$lang['xp_to_go']               = '%1$s XP until level %2$s';
 
$lang['skill_level']		= 'Skill level';
 
// Last Online words
$lang['online_at_update']       = 'Online bei Update';
$lang['second']                 = 'vor %s Sekunde';
$lang['seconds']                = 'vor %s Sekunden';
$lang['minute']                 = 'vor %s Minute';
$lang['minutes']                = 'vor %s Minuten';
$lang['hour']                   = 'vor %s Stunde';
$lang['hours']                  = 'vor %s Stunden';
$lang['day']                    = 'vor %s Tag';
$lang['days']                   = 'vor %s Tagen';
$lang['week']                   = 'vor %s Woche';
$lang['weeks']                  = 'vor %s Wochen';
$lang['month']                  = 'vor %s Monat';
$lang['months']                 = 'vor %s Monaten';
$lang['year']                   = 'vor %s Jahr';
$lang['years']                  = 'vor %s Jahren';
 
$lang['armor_tooltip']			= 'Verringert den erlittenen kÃ¶rperlichen Schaden um %1$s%%';
 
$lang['motd']                   = 'MOTD';
$lang['accounts']               = 'Accounts';
 
// Configuration
$lang['memberslist_config']		= 'Gehe zur Mitgliederliste-Konfiguration';
$lang['memberslist_config_page']= 'Mitgliederliste-Konfiguration';
$lang['documentation']			= 'Dokumentation';
$lang['uninstall']				= 'Uninstall';
 
// Page names
$lang['admin']['display']       = 'Anzeige|Konfiguriert die Anzeigeoptionen fÃ¼r die Mitgliederliste.';
$lang['admin']['members']       = 'Mitgliederliste|Konfiguriert die Sichtbarkeit der Mitgliederliste-Spalten.';
$lang['admin']['stats']         = 'Werteliste|Konfiguriert die Sichtbarkeit der Grundwerte-Spalten.';
$lang['admin']['honor']         = 'Ehrenliste|Konfiguriert die Sichtbarkeit der Ehrenliste-Spalten.';
$lang['admin']['log']           = 'Mitglieder Log|Konfiguriert die Sichtbarkeit der Mitglieder Log-Spalten.';
$lang['admin']['build']         = 'Hauptchar/Twink Beziehungen|Konfiguriert wie Hauptchars/Twinks erkannt werden.';
$lang['admin']['ml_wiki']       = 'Dokumentation|Mitgliederliste Dokumentation auf WoWRoster wiki.';
$lang['admin']['updMainAlt']    = 'Aktualisiere Beziehungen|Aktualisiert die Main/Alt Beziehungen der Daten, die bereits in der DB gespeichert sind.';
$lang['admin']['page_size']		= 'SeitengrÃ¶ÃŸe|Konfiguriert die Anzahl der Zeilen Pro Seite oder 0 fÃ¼r keinen Seitenumbruch';

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->

Views

AddonSDK

From WoWRosterWiKi

WoWRoster v2.0.0 AddOn Development

Changes

Contents

Info and Download

Certified WoWRoster AddOn

Requirements for Approval

Basics of an AddOn

Changes Since 1.7.3

AddOn Framework

Features

What it does

AddOn Directory Structure

admin Folder

char Folder (character scope)

guild Folder (guild scope)

inc Folder

locale Folder

realm Folder (realm scope)

The util Scope

Other Files

Required Files

Linking to AddOns

Creating the Installer

Properties

AddOn Install Class Methods

Queries

RosterCP API Entries

Creating/Editing Menu Entries

Other Installer Methods

Example File

Creating the Search Class

Addon Class

Properties

Methods

Constructor

search

add_result

Return Data

Search Framework Variables

Example File

Roster Config API

Menu Bar Items

Usage

Options Blocks

Options

AddOn Config Function File

Locale Files

Using Locale Strings

Example File

CSS Styles

Template Parser

Getting Started

The PHP Side