Roster:Addon:AddonSDK

From WoWRosterWiKi
(Difference between revisions)
Jump to: navigation, search
(Redirecting to AddonSDK)
 
Line 1: Line 1:
__NOEDITSECTION__
+
#REDIRECT [[AddonSDK]]
{{Disclaimer}}
+
{{MainMenu|Roster}}
+
 
+
=WoWRoster v1.8.0 AddOn Development=
+
Readme Updated: 01:07, 1 July 2007 (PDT)
+
 
+
* 01:07, 1 July 2007 (PDT) - Paths to install.def.php, conf.php, and update_hook.php have been changed
+
*: Also changed the importance of the inc/ folder
+
 
+
 
+
 
+
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<br />
+
And Everyone involved in the project.
+
 
+
 
+
'''Download the [http://www.wowroster.net/Downloads/details/id=32.html Roster AddOnSDK]'''
+
 
+
 
+
 
+
 
+
==Certified WoWRoster AddOn==
+
[[Image:Certaddon.png|frame|Certified WoWRoster AddOn]]
+
AddOns that conform to our [[CodingStandards|Coding Standards]] and the basic outline described within this document, will be given a "<span style="color:maroon;">AddOn Framework Standards Compliant</span>" 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 [[Roster:CP|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 (BOM characters displaying above the menu for example)
+
*: (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 - <span style="color:maroon;">$roster->db</span>
+
* 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<br>
+
>[[Roster:Requirements|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.<br>
+
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.<br>
+
So with each new version of Roster, some AddOns may break (not work in the new WoWRoster)
+
 
+
<div style="margin:5px 0 5px 0;">
+
{| width="100%" style="clear:both;border:2px inset #ff3300;border-collapse:collapse;padding:0.2em;margin:0;margin:0 1px;"
+
|- valign="top" style="background:#FFEBE6"
+
|style="width:25px;padding-left:0.5em;"|[[Image:Tools clipart.png|20px]]
+
|style="width:10px;white-space:nowrap;padding:4px 1em 0 0.5em;border-right:1px solid #ff3300;"|'''Important:'''
+
|style="padding:1px 1em 0;background:#F6F9ED;"|
+
DO NOT use php short tags in your php files<br>
+
This is also stated in the [[CodingStandards|WoWRoster Coding Standards]]<br>
+
<span style="color:red;">NO!</span> <code><?    ?></code><br>
+
<span style="color:green;">YES</span> <code><?php  ?></code><br>
+
<span style="color:red;">NO!</span> <code><?=$var; ?></code><br>
+
<span style="color:green;">YES</span> <code><?php echo $var; ?></code><br>
+
Use the "long tags" as the short ones can break web servers with short_tags set to "off"
+
|}
+
</div>
+
 
+
 
+
 
+
==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 in addon.php, most notably $addonDir, have changed names.
+
* localization.php is no longer used.
+
** Locale files are now placed in the locale subfolder of the addon and are named for the locale they are made for
+
* 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.
+
* 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 file reader and creator
+
 
+
 
+
==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 <span style="color:maroon;">$roster</span> 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 (<span style="color:maroon;">$roster</span>->config)
+
# Includes all Roster SQL functions for your use (<span style="color:maroon;">$roster</span>->db)
+
# Includes all Roster and AddOn language variables for you (<span style="color:maroon;">$roster</span>->locale->wordings, <span style="color:maroon;">$roster</span>->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
+
<pre>roster/
+
|_ addons/
+
  |_ addonname/
+
      |_ admin/
+
      |  |_ index.php
+
      |  |_ other.php
+
      |
+
      |_ char/
+
      |  |_ index.php
+
      |  |_ other.php
+
      |
+
      |_ guild/
+
      |  |_ index.php
+
      |  |_ other.php
+
      |
+
      |_ guildless/
+
      |  |_ index.php
+
      |  |_ other.php
+
      |
+
      |_ inc/
+
      |  |_ conf.php
+
      |  |_ functions.php
+
      |  |_ install.def.php
+
      |  |_ update_hook.php
+
      |
+
      |_ locale/
+
      |  |_ deDE.php
+
      |  |_ enUS.php
+
      |  |_ esES.php
+
      |  |_ frFR.php
+
      |
+
      |_ realm/
+
      |  |_ index.php
+
      |  |_ other.php
+
      |
+
      |_ index.php
+
      |_ somefile.php
+
      |_ util.php
+
</pre>
+
 
+
 
+
 
+
====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<br>
+
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====
+
Files for use in the Character scope<br>
+
Data for the requested character is passed to the AddOn<br>
+
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
+
 
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=name@realm
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=##.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=name@realm.html
+
 
+
Accessing other files in the char scope is easy<br>
+
addons/addonname/addonname/char/file.php is accessed like this:
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname-file&member=##
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/file/member=##.html
+
 
+
 
+
 
+
====guild Folder====
+
Files for use in the Guild scope<br>
+
Data for the requested guild is passed to the AddOn<br>
+
If guild= is not specified, the default guild/realm name set in Roster CP will show<br>
+
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
+
 
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=name@realm
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=##.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=name@realm.html
+
 
+
Accessing other files in the guild scope is easy<br>
+
addons/addonname/guild/file.php is accessed like this:
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname-file&guild=##
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/file/guild=##.html
+
 
+
 
+
 
+
====guildless Folder====
+
Files for use in the Guildless scope<br>
+
Data for the requested realm is passed to the AddOn<br>
+
If realm= is not specified, the default realm name set in Roster CP will show<br>
+
If the realm does not exist or if there is no data for this realm, an error message will display
+
 
+
realm= can be text
+
 
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guildless-addonname&realm=name
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guildless/addonname/realm=name.html
+
 
+
Accessing other files in the guildless scope is easy<br>
+
addons/addonname/guildless/file.php is accessed like this:
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guildless-addonname-file&realm=name
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guildless/addonname/file/realm=name.html
+
 
+
 
+
 
+
====inc Folder====
+
This folder houses special files not meant for direct access by the AddOn Framework<br>
+
These files are conf.php, install.def.php, and update_hook.php<br>
+
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<br>
+
See below for more info [[#Locale Files|Locale Files]]
+
 
+
 
+
 
+
====realm Folder====
+
Files for use in the Realm scope<br>
+
Data for the requested realm is passed to the AddOn<br>
+
If realm= is not specified, the default realm name set in Roster CP will show<br>
+
If the realm does not exist or if there is no data for this realm, an error message will display
+
 
+
realm= can be text
+
 
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&realm=name
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/realm=name.html
+
 
+
Accessing other files in the realm scope is easy<br>
+
addons/addonname/realm/file.php is accessed like this:
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=realm-addonname-file&realm=name
+
* SEO Link - http://[www.someurl.net]/roster/trunk/realm/addonname/file/realm=name.html
+
 
+
 
+
 
+
====Other Files and the util Scope====
+
Files not in these folders are considered under the util scope<br>
+
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<br>
+
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
+
 
+
* inc/conf.php - This is included before any other addon file, any initialization can be done here
+
* index.php - The main file for the util scope
+
* [[#Creating_the_Installer|inc/install.def.php]] - The AddOn's install/upgrade/uninstall definition file
+
* [[#CSS_Styles|style.css]] - A custom css style for the AddOn
+
* [[#AddOn_Update_Hook|inc/update_hook.php]] - Update Hook file
+
 
+
 
+
 
+
===Required Files===
+
There are a few files that you must have
+
* [[#Creating_the_Installer|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, guildless, guild, char, util
+
*: Realm (realm) - Page that uses realm information (realm=name is appended to the url)
+
*: GuildLess (guildless) - Page that uses realm information for unguilded data (realm=name is appended to the url)
+
*: Guild (guild) - Page that uses guild information (guild=id# or guild=name@server is appended to the url)
+
*: Character (char) - Page that uses character information (member=id# or member=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 pages (rostercp, update, credits, search)
+
* addonname - The name of the AddOn you are accessing
+
* file - The file you are accessing
+
 
+
 
+
 
+
==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 <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>)
+
* No rollback data per query. Instead, call <span style="color:maroon;">$installer</span>->add_backup(<span style="color:maroon;">$table_name</span>) 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.<br>
+
This name will be referred to as your AddOn's basename.
+
 
+
 
+
 
+
===Properties===
+
* var <span style="color:maroon;">$active</span>
+
*: Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.
+
 
+
* var <span style="color:maroon;">$version</span>
+
*: String, the current version of your AddOn.
+
*: Needs to be compatible with php's version_compare().
+
*: Should be incremented on every update that includes a database update, or any update if you wish.
+
 
+
* var <span style="color:maroon;">$icon</span>
+
*: String, an icon to display for your AddOn in the AddOn management page in RosterCP
+
*: Valid icons are from the Interface ImagePack
+
 
+
* var <span style="color:maroon;">$fullname</span>
+
*: String, the full name of the AddOn for display.
+
 
+
* var <span style="color:maroon;">$description</span>
+
*: String, a sort description of your AddOn.
+
 
+
* var <span style="color:maroon;">$credits</span>
+
*: Credits information.
+
<php>$credits = array(
+
array( "name"=> "Name",
+
"info"=> "Some Info"),
+
array( "name"=> "Another Name",
+
"info"=> "More Info"),
+
);</php>
+
 
+
 
+
 
+
===Methods===
+
* install()
+
*: Here you can add all queries for a fresh install.
+
*: No parameters.
+
*: Return true on success, false on failure.
+
 
+
* upgrade(<span style="color:maroon;">$oldversion</span>)
+
*: Here you can add all queries for an upgrade.
+
*:: <span style="color:maroon;">$oldversion</span>, the version you are upgrading from.
+
*: Return true on success, false on failure.
+
{{Note|You should supply your own file to be called for upgrades of a Roster 1.7.x AddOn since Roster 1.8 cannot detect these AddOns.}}
+
 
+
* uninstall()
+
*: Here you should add all queries for an uninstall.
+
*: No parameters.
+
*: Return true on success, false on failure
+
 
+
 
+
 
+
===Adding Queries===
+
Queries are added to the install using the <span style="color:maroon;">$installer</span> methods.
+
 
+
* <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>);
+
*: Any valid SQL query
+
 
+
* <span style="color:maroon;">$installer</span>->add_backup(<span style="color:maroon;">$table</span>)
+
*: Makes a temporary copy of a table and its contents that is put back in case of a rollback
+
 
+
* <span style="color:maroon;">$installer</span>->add_drop(<span style="color:maroon;">$table</span>)
+
*: Have a table be dropped on rollback
+
 
+
* <span style="color:maroon;">$installer</span>->add_config(<span style="color:maroon;">$sqlstring</span>);
+
*: Add config sql to `roster_addon_config` table
+
*: Format is "'id','config_name','config_value','form_type','config_type'"
+
*: These entries will be used to build a config page through Roster's config page API
+
 
+
 
+
 
+
===Creating/Editing Menu Entries===
+
There are 3 separate functions for this.<br>
+
Note the title should be unique per AddOn.
+
 
+
* <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>)
+
*: Adds a menu button. Parameters:
+
*: <span style="color:maroon;">$title</span>
+
*:: The localization key for the menu button's title.
+
*: <span style="color:maroon;">$scope</span>
+
*:: The scope of the link ('util','realm','guild','guildless','char')
+
*: <span style="color:maroon;">$url</span>
+
*:: The url parameters this button should call the AddOn with
+
*: <span style="color:maroon;">$icon</span>
+
*:: An icon to display in the button
+
 
+
* <span style="color:maroon;">$installer</span>->update_menu_button($title, $scope, $url, $icon)
+
*: Changes menu button. Parameters:
+
*: <span style="color:maroon;">$title</span>
+
*:: The localization key for the menu button's title.
+
*: <span style="color:maroon;">$scope</span>
+
*:: The scope of the link ('util','realm','guild','guildless','char')
+
*: <span style="color:maroon;">$url</span>
+
*:: The url parameters this button should call the AddOn with
+
*: <span style="color:maroon;">$icon</span>
+
*:: An icon to display in the button
+
 
+
* <span style="color:maroon;">$installer</span>->remove_menu_button($title)
+
*: Removes a menu button. Parameters:
+
*: <span style="color:maroon;">$title</span>
+
*:: The localization key for the menu button's title.
+
 
+
 
+
 
+
===Example File===
+
Here is an example of an AddOn install file<br>
+
From the "Keys" AddOn
+
 
+
You can find more examples in the addons/ folder in roster
+
<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: install.def.php 897 2007-05-06 00:35:11Z Zanix $
+
* @link      http://www.wowroster.net
+
* @package    InstanceKeys
+
* @subpackage Installer
+
*/
+
 
+
if ( !defined('ROSTER_INSTALLED') )
+
{
+
    exit('Detected invalid access to this file!');
+
}
+
 
+
/**
+
* Installer Instance Keys Addon
+
*
+
* @package    InstanceKeys
+
* @subpackage Installer
+
*/
+
class keys
+
{
+
var $active = true;
+
var $icon = 'inv_misc_key_06';
+
 
+
var $upgrades = array(); // There are no previous versions to upgrade from
+
 
+
var $version = '1.8.0.0';
+
 
+
var $fullname = 'Instance Keys';
+
var $description = 'Lists Azeroth Dungeon keys for Members';
+
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','keys_conf',NULL,'blockframe','menu'");
+
 
+
$installer->add_config("'1010','colorcmp','#00ff00','color','keys_conf'");
+
$installer->add_config("'1020','colorcur','#ffd700','color','keys_conf'");
+
$installer->add_config("'1030','colorno','#ff0000','color','keys_conf'");
+
 
+
$installer->add_menu_button('keys','guild');
+
return true;
+
}
+
 
+
/**
+
* Upgrade Function
+
*
+
* @param string $oldversion
+
* @return bool
+
*/
+
function upgrade($oldversion)
+
{
+
// Nothing to upgrade from yet
+
return false;
+
}
+
 
+
/**
+
* Un-Install Function
+
*
+
* @return bool
+
*/
+
function uninstall()
+
{
+
global $installer;
+
 
+
$installer->remove_all_config();
+
 
+
$installer->remove_menu_button('keys');
+
return true;
+
}
+
}</php>
+
 
+
 
+
 
+
==Roster Config API==
+
This is the current functionality of the Roster Config API.<br>
+
There are two classes of form types:
+
* Option blocks for layout
+
* Actual options
+
Items of the page, pageframe, and pagehide class contain option blocks.<br>
+
Items of the blockframe or blockhide class contain options.
+
 
+
 
+
 
+
===Menu Bar Items===
+
* page, pageframe, pagehide, blockframe, blockhide:
+
*: A page of options that gets selected with javascript
+
*: <span style="color:maroon;">$installer</span>->add_config("'110','config_name',NULL,'blockframe','menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'150', 'config_name', NULL, 'page{1', 'menu'")
+
 
+
* link
+
*: An external link to be opened in the same window
+
*: <span style="color:maroon;">$installer</span>->add_config("120,'config_name','link_value','link','menu'")
+
 
+
* newlink
+
*: An external link to be opened in a new window
+
*: <span style="color:maroon;">$installer</span>->add_config("170,'config_name','<nowiki>http://www.someurl.com</nowiki>','newlink','menu'")
+
 
+
* makelink
+
*: Passes this through Roster's makelink() function to generate a correct link to another page in Roster.
+
*: <span style="color:maroon;">$installer</span>->add_config("120,'config_name','link_value','makelink','menu'")
+
 
+
* makenewlink
+
*: Same as makelink, except it opens a new browser window.
+
*: <span style="color:maroon;">$installer</span>->add_config("180,'config_name','link_value','makenewlink','menu'")
+
 
+
 
+
 
+
===Options Blocks===
+
* page{n
+
*: n columns of options blocks
+
*: <span style="color:maroon;">$installer</span>->add_config("'4001', 'menu_conf_wide', NULL, 'page{2', 'menu_conf'")
+
 
+
* pageframe{n
+
*: n columns of options blocks in a border
+
*: <span style="color:maroon;">$installer</span>->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
+
*: <span style="color:maroon;">$installer</span>->add_config("'4020', 'menu_conf_hidden', NULL, 'pagehide{1', 'menu_conf'")
+
 
+
* blockframe
+
*: A list of options in a border
+
*: <span style="color:maroon;">$installer</span>->add_config("'4000, 'menu_conf_top', NULL, 'blockframe', 'menu_conf'")
+
 
+
* blockhide
+
*: A list of options in a border, with a show/hide option
+
*: <span style="color:maroon;">$installer</span>->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.
+
*: <span style="color:maroon;">$installer</span>->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
+
*: <span style="color:maroon;">$installer</span>->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.
+
*: <span style="color:maroon;">$installer</span>->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.
+
*: <span style="color:maroon;">$installer</span>->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.
+
*: <span style="color:maroon;">$installer</span>->add_config("'4270', 'left_text', 'VERANDA.TTF', 'function{fontFiles', 'menu_conf_top'")
+
 
+
* display
+
*: Displays the option's setting.
+
*: <span style="color:maroon;">$installer</span>->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
+
*: <span style="color:maroon;">$installer</span>->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.<br>
+
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:
+
<pre>roster/
+
|_ addons/
+
  |_ addonname/
+
      |_ locale/
+
        |_ deDE.php
+
        |_ enUS.php
+
        |_ esES.php
+
        |_ frFR.php</pre>
+
When using locale files, it is absolutely necessary to ALWAYS have enUS.php<br>
+
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
+
<php>$header_title = $roster->locale->wordings['locale_key']['some_key'];</php>
+
or
+
<php>$header_title = $roster->locale->act['some_key'];</php>
+
The first example is to get a specific locale value<br>
+
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<br>
+
addons/questlist/locale/deDE.php
+
<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";
+
</php>
+
 
+
 
+
 
+
==CSS Styles==
+
CSS style from the MembersList AddOn
+
<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;
+
}</css>
+
 
+
I assume you know what css is...
+
 
+
 
+
 
+
==AddOn Update Hook==
+
The update hook is a file that ties into the lua upload process<br>
+
You can specify any additional lua files you may you need
+
 
+
There are a few hook modes that an AddOn can make use of
+
* update
+
** This mode does not hook into the CharacterProfiler upload process and is a good way to parse and process data from lua files other than CharacterProfiler
+
* char_pre
+
** This mode is fired before any character is processed
+
* char
+
** This mode fires for every character that is processed
+
* char_post
+
** This mode is fired after every character is processed
+
* guild_pre
+
** This mode is fired for each guild processed before any guild members are processed
+
* guild
+
** This mode is fired for each guild processed and for each guild member processed
+
* guild_post
+
** This mode is fired for each guild processed after guild members are processed
+
 
+
 
+
 
+
===Properties===
+
The following variables are required in the update hook class
+
 
+
* var <span style="color:maroon;">$messages</span>
+
*: String, any messages or output.
+
 
+
* var <span style="color:maroon;">$data</span>
+
*: Array, Addon data object, recieved in constructor.
+
*: This holds the addon's data from the database
+
 
+
* var <span style="color:maroon;">$icon</span>
+
*: String, an icon to display for your AddOn in the AddOn management page in RosterCP
+
*: Valid icons are from the Interface ImagePack
+
 
+
* var <span style="color:maroon;">$files</span>
+
*: array, An array of additional lua files that your addon needs.
+
*: If you are using CharacterProfiler for data, there is no need to list it here.
+
 
+
 
+
 
+
===Methods===
+
* addonUpdate()
+
*: The constructor for the update hook
+
*: This is the only required method in an update hook class
+
*: The addons data is passed to this function, you should set the passed data to an internal property variable
+
<php> function addonUpdate($data)
+
{
+
$this->data = $data;
+
}</php>
+
 
+
The following methods are reserved for update hooks<br>
+
Descriptions for these methods are above and are not required
+
 
+
These function fairly simmilar
+
* update()
+
* char_pre(<span style="color:maroon;">$characters</span>)
+
** <span style="color:maroon;">$characters</span> - Array: All characters and their data in CharacterProfiler.lua
+
* char(<span style="color:maroon;">$char</span>, <span style="color:maroon;">$memberid</span>)
+
** <span style="color:maroon;">$char</span> - Array: Character data array for the current processed character
+
** <span style="color:maroon;">$memberid</span> - Int: Member id from members table
+
* char_post(<span style="color:maroon;">$characters</span>)
+
** <span style="color:maroon;">$characters</span> - Array: All characters and their data in CharacterProfiler.lua
+
* guild_pre(<span style="color:maroon;">$guild</span>)
+
** <span style="color:maroon;">$guild</span> - Array: All guilds and their data in CharacterProfiler.lua
+
* guild(<span style="color:maroon;">$char</span>, <span style="color:maroon;">$memberid</span>)
+
** <span style="color:maroon;">$char</span> - Array: Member data array for the current processed member
+
** <span style="color:maroon;">$memberid</span> - Int: Member id from members table
+
* guild_post(<span style="color:maroon;">$guild</span>)
+
** <span style="color:maroon;">$guild</span> - Array: All guilds and their data in CharacterProfiler.lua
+
 
+
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<br>
+
Look at memberslist and pvplog (example of additional lua file upload and processing) for more complex examples
+
<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: update_hook.php 899 2007-05-06 10:16:36Z Zanix $
+
* @link      http://www.wowroster.net
+
* @package    AddOnName
+
*/
+
 
+
if ( !defined('ROSTER_INSTALLED') )
+
{
+
    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;
+
}
+
}</php>
+
 
+
 
+
===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.
+
<php>$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</php>
+
 
+
$roster->output['show_menu'] can accept a string or an array of button listings to display<br>
+
When building an addon, you can build your own button listing that only displays on your addon pages<br>
+
Pass a string for only one set of buttons, or pass an array for multiple sets of buttons
+
<php>$roster->output['show_menu'] = 'main';  // Display the main button listing
+
$roster->output['show_menu'] = array('main','char');  // Display the main and char button listing</php>
+
 
+
<php>$roster->output['html_head'] = 'string';</php>
+
Accepts any string needing to be in the html header for your addon, such as javascript inclusion<br>
+
roster_header.tpl will pick this variable up and place its contents in the header
+
 
+
<php>$roster->output['body_attr'] = 'string';</php>
+
Accepts any string needing to be in the <body> tag in roster_header.tpl
+
 
+
<php>$roster->output['body_onload'] = 'string';</php>
+
Accepts any string needing to be in <body onload=""> in roster_header.tpl
+
 
+
 
+
Any output needed, just print or echo it<br>
+
Roster uses php's output buffering to capture all print or echo commands<br>
+
Then it echos the output where needed
+
 
+
 
+
 
+
===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
+
 
+
* <span style="color:maroon;">$roster</span>->db
+
** Database layer for roster
+
* <span style="color:maroon;">$roster</span>->locale->wordings
+
** Every locale array
+
* <span style="color:maroon;">$roster</span>->locale->act
+
** The current global locale string array
+
* <span style="color:maroon;">$roster</span>->config
+
** The roster configuration array
+
* <span style="color:maroon;">$roster</span>->pages
+
** Array of current pages accessed
+
* <span style="color:maroon;">$roster</span>->data
+
** Current scope data
+
*: For a list of what is in here, see RosterDiag
+
* DIR_SEP
+
** OS specific directory separator
+
* ROSTER_BASE
+
** Full path to roster directory including DIR_SEP at the end
+
* ROSTER_LIB
+
** Full path to roster lib directory including DIR_SEP at the end
+
* ROSTER_ADDONS
+
** Full path to roster addons directory including DIR_SEP at the end
+
* ROSTER_ADMIN
+
** Full path to roster admin directory including DIR_SEP at the end
+
* ROSTER_AJAX
+
** Full path to rosters ajax directory including DIR_SEP at the end
+
* ROSTER_LOCALE
+
** Full path to roster localization directory including DIR_SEP at the end
+
* ROSTER_VERSION
+
** Current Version of Roster
+
* ROSTER_URL
+
** Full valid URL to roster's root directory
+
* ROSTER_PATH
+
** URL path to roster's root directory
+
* ROSTER_INSTALLED
+
** Constant saying that Roster is installed
+
*: (addon.php already detects for this and dies if not found)
+
* ROSTER_MAXCHARLEVEL
+
*: Maximum level that a character in WoW can achieve
+
* ROSTER_MAXSKILLLEVEL
+
*: Maximum skill level that a character in WoW can achieve
+
* <span style="color:maroon;">$roster</span>->db->prefix
+
** Database table prefix
+
* <span style="color:maroon;">$roster</span>->db->table(<span style="color:maroon;">$tablename</span>, <span style="color:maroon;">$addon</span>='')
+
** Returns a table name including the database prefix
+
*** This will return 'databaseprefix_tablename'
+
** When $addon is passed, use the basename of the addon
+
*** This will return 'databaseprefix_addon_basename_tablename'
+
* <span style="color:maroon;">$addon</span>['addon_id']
+
** Addon database id
+
* <span style="color:maroon;">$addon</span>['basename']
+
** Addon folder name
+
* <span style="color:maroon;">$addon</span>['version']
+
** Addon version
+
* <span style="color:maroon;">$addon</span>['active']
+
** 0 - if the Addon is disabled : 1 -  if the Addon is enabled
+
** Use addon_active('basename') to check if an addon is enabled
+
* <span style="color:maroon;">$addon</span>['fullname']
+
** Addon's full name for display
+
* <span style="color:maroon;">$addon</span>['description']
+
** Short description of the addon
+
* <span style="color:maroon;">$addon</span>['credits']
+
** Serialized array of credits
+
* <span style="color:maroon;">$addon</span>['icon']
+
** Addon's display icon
+
* <span style="color:maroon;">$addon</span>['dir']
+
** Full path to the Addon's folder
+
* <span style="color:maroon;">$addon</span>['css_file']
+
** Full path to the Addon's style.css file
+
* <span style="color:maroon;">$addon</span>['css_url']
+
** URL path to the Addon's css file, this is not the full url path
+
* <span style="color:maroon;">$addon</span>['conf_file']
+
** Full path to the Addon's inc/conf.php file
+
* <span style="color:maroon;">$addon</span>['locale_dir']
+
** Full path to the Addon's locale directory
+
* <span style="color:maroon;">$addon</span>['admin_dir']
+
** Full path to the Addon's admin directory
+
* <span style="color:maroon;">$addon</span>['trigger_file']
+
** Full path to the Addon's inc/update_hook.php file
+
* <span style="color:maroon;">$addon</span>['ajax_file']
+
** Full path to the Addon's ajax.php
+
* <span style="color:maroon;">$addon</span>['config']
+
** Addon's configuration array
+
 
+
 
+
 
+
====Functions====
+
This is a list of functions that are available for your Addons
+
 
+
<php>/**
+
* Starts or ends fancy bodering containers
+
*
+
* @param string $style What bordering style to use
+
* @param string $mode ( 'start' | 'end' )
+
* @param string $header_text (optional) Place text in a styled header
+
* @return string
+
*/
+
function border($style,$mode,$header_text=null)</php>
+
 
+
<php>/**
+
* Highlight certain keywords in a SQL query
+
*
+
* @param string $sql Query string
+
* @return string Highlighted string
+
*/
+
function sql_highlight( $sql )</php>
+
 
+
<php>/**
+
* 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='' )</php>
+
 
+
<php>/**
+
* 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' )</php>
+
 
+
<php>/**
+
* 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)</php>
+
 
+
<php>/**
+
* 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 )</php>
+
 
+
<php>/**
+
* Recursively escape $array
+
*
+
* @param array $array The array to escape
+
* @return array The same array, escaped
+
*/
+
function escape_array( $array )</php>
+
 
+
<php>/**
+
* Converts a datetime field into a readable date
+
*
+
* @param string $datetime datetime field data in DB
+
* @return string formatted date string
+
*/
+
function readbleDate( $datetime )</php>
+
 
+
<php>/**
+
* Gets a file's extention passed as a string
+
*
+
* @param string $filename
+
* @return string
+
*/
+
function get_file_ext( $filename )</php>
+
 
+
<php>/**
+
* 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 )</php>
+
 
+
<php>/**
+
* Check to see if an addon is active or not
+
*
+
* @param string $name | Addon basename
+
* @return bool
+
*/
+
function active_addon( $name )</php>
+
 
+
<php>/**
+
* Handles retrieving the contents of a URL using multiple methods
+
*
+
* @param string $url | URL to retrieve
+
* @param int $timeout | Timeout
+
* @return mixed | False on error, contents on success
+
*/
+
function urlgrabber( $url , $timeout = 5 )</php>
+
 
+
 
+
 
+
====Roster Authorization====
+
Like those nifty log-in boxes in Roster CP?<br>
+
Now you can easily add one to your addon!
+
 
+
This checks if the user has admin access
+
<php>// ----[ 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 ]---------------------------------</php>
+
* <span style="color:maroon;">$roster_login</span> - Roster Login class
+
* <span style="color:maroon;">$roster_login</span>->getAuthorized() - (int) Returns the id of access
+
** 1 - Guild Memeber Access
+
** 2 - Officer Access
+
** 3 - Roster Admin Access
+
* <span style="color:maroon;">$roster_login</span>->getMessage() - (string) Message sent from Roster Login, such as "Logged In", "Logged Out", or "Wrong Password"
+
* <span style="color:maroon;">$roster_login</span>->getLoginForm() - (string) The Roster Log-in form
+
 
+
 
+
 
+
====Addon Credits====
+
Link = http://[www.someurl.net]/roster/?p=credits (SEO: http://[www.someurl.net]/roster/credits.html)<br>
+
To get credits on the main credit page, set the $credits array in the AddOn's inc/install.def.php file
+
<php>var $credits = array(
+
array( "name"=> "Author Name",
+
"info"=> "Extra Info"),
+
);</php>
+
Replace the following
+
*"Addon Name" with your addon's name
+
*"Author Name" with your (The addon's author) name
+
*"Extra Info" with a short description or additional info
+
(Use <nowiki><br></nowiki> for line breaks)
+
 
+
You can add multiple arrays inside the main one to add more credits<br>
+
(Try not to add too many, we don't wanna clutter the credits page now do we?)
+
 
+
 
+
 
+
====Tooltips====
+
<php>/**
+
* Makes a tootip and places it into the tooltip array
+
*
+
* @param string $var
+
* @param string $content
+
*/
+
function setTooltip( $var , $content )</php>
+
Creates a js variable for use with overlib<br>
+
Instead of outputting text in the html, you can create a js variable that holds this instead
+
<php>/**
+
* 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='' )</php>
+
Returns this string for use in any html tag that supports onmouseover and onmouseout events
+
<pre>onmouseover="return overlib(overlib_'.$num_of_tips.$caption.$extra_parameters.');" onmouseout="return nd();"</pre>
+
For more info about makeOverlib() and its supporting functions, look at functions.lib.php
+
 
+
 
+
 
+
====Message Boxes====
+
Functions to draw message boxes
+
<php>/**
+
* 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
+
* @return string $html | The HTML for the messagebox
+
*/
+
function messagebox($message, $title = 'Message', $style = 'sgray')</php>
+
 
+
<php>/**
+
* 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')</php>
+
 
+
<php>/**
+
* 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')</php>
+
 
+
<php>/**
+
* 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')</php>
+
 
+
[[Category:RosterAddon]]
+

Latest revision as of 02:03, 2 July 2007

  1. REDIRECT AddonSDK
Personal tools
Namespaces
Variants
Actions
WoWRoster
Preview Roster
Navigation
Toolbox