Roster:Addon:AddonSDK

From WoWRosterWiKi
(Difference between revisions)
Jump to: navigation, search
Line 58: Line 58:
 
So with each new version of Roster, some AddOns may break (not work in the new WoWRoster)
 
So with each new version of Roster, some AddOns may break (not work in the new WoWRoster)
  
<blockquote style="border:2px outset red;padding:3px;">IMPORTANT:<br>
+
<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>
 
DO NOT use php short tags in your php files<br>
 
This is also stated in the [[CodingStandards|WoWRoster Coding Standards]]<br>
 
This is also stated in the [[CodingStandards|WoWRoster Coding Standards]]<br>
Line 64: Line 69:
 
<span style="color:green;">YES</span> <code><?php  ?></code><br>
 
<span style="color:green;">YES</span> <code><?php  ?></code><br>
 
Use the "long tags" as the short ones can break web servers with short_tags set to "off"
 
Use the "long tags" as the short ones can break web servers with short_tags set to "off"
</blockquote>
+
|}
 +
</div>
  
  
  
  
==AddOn Framework==
 
Ok so here we are, working on a AddOn and you're thinking, "How am I going to get the conf and language variables to use in my AddOn?"<br>
 
Well our answer to that is, it's done for you!
 
  
 +
==AddOn Framework==
  
 
===Features===
 
===Features===
Line 86: Line 90:
 
===What it does===
 
===What it does===
 
# Includes all Roster config variables for you to use ($roster->config)
 
# Includes all Roster config variables for you to use ($roster->config)
# Includes all Roster sql functions for your use ($roster->db)
+
# Includes all Roster SQL functions for your use ($roster->db)
 
# Includes all Roster language variables for you ($roster->locale->wordings, $roster->locale->act)
 
# Includes all Roster language variables for you ($roster->locale->wordings, $roster->locale->act)
 
# Includes all Roster css styles
 
# Includes all Roster css styles
Line 109: Line 113:
 
       |
 
       |
 
       |_ guild/
 
       |_ guild/
 +
      |  |_ index.php
 +
      |  |_ other.php
 +
      |
 +
      |_ guildless/
 
       |  |_ index.php
 
       |  |_ index.php
 
       |  |_ other.php
 
       |  |_ other.php
Line 120: Line 128:
 
       |  |_ esES.php
 
       |  |_ esES.php
 
       |  |_ frFR.php
 
       |  |_ frFR.php
 +
      |
 +
      |_ realm/
 +
      |  |_ index.php
 +
      |  |_ other.php
 
       |
 
       |
 
       |_ conf.php
 
       |_ conf.php
 
       |_ index.php
 
       |_ index.php
 
       |_ install.def.php
 
       |_ install.def.php
 +
      |_ somefile.php
 
       |_ update_hook.php
 
       |_ update_hook.php
 +
      |_ util.php
 
</pre>
 
</pre>
  
Line 133: Line 147:
 
If you do need a custom config interface, this is where you make it
 
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
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-addonname-file
* SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/addonname.html
+
* 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
 
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
Line 157: Line 172:
 
member= can be either the member id number, or name@realm text
 
member= can be either the member id number, or name@realm text
  
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-info&member=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=##
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-info&member=name@realm
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=name@realm
* SEO Link - http://[www.someurl.net]/roster/trunk/char/info.html?member=##
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=##.html
* SEO Link - http://[www.someurl.net]/roster/trunk/char/info.html?member=name@realm
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=name@realm.html
  
 
Accessing other files in the char scope is easy<br>
 
Accessing other files in the char scope is easy<br>
addons/addonname/info/char/bags.php is accessed like this:
+
addons/addonname/addonname/char/file.php is accessed like this:
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-info-bags&member=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname-file&member=##
* SEO Link - http://[www.someurl.net]/roster/trunk/char/info/bags.html?member=##
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/file/member=##.html
  
  
Line 177: Line 192:
 
guild= can be either the guild id number, or name@realm text
 
guild= can be either the guild id number, or name@realm text
  
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-memberslist&guild=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=##
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-memberslist&guild=name@realm
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=name@realm
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/memberslist.html?guild=##
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=##.html
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/memberslist.html?guild=name@realm
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=name@realm.html
  
 
Accessing other files in the guild scope is easy<br>
 
Accessing other files in the guild scope is easy<br>
addons/addonname/memberslist/guild/honorlist.php is accessed like this:
+
addons/addonname/guild/file.php is accessed like this:
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-memberslist-honorlist&guild=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname-file&guild=##
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/memberslist/honorlist.html?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
  
  
Line 193: Line 226:
 
It can be lib, library, functions, etc...
 
It can be lib, library, functions, etc...
  
Place any files here that you do not or should not be accessed by the AddOn Framework
+
Place any files here that you do not or should not be accessed directly by the AddOn Framework
  
  
Line 199: Line 232:
 
Where locale translation files go<br>
 
Where locale translation files go<br>
 
See below for more info [[#Locale Files|Locale Files]]
 
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
  
  
Line 211: Line 261:
  
 
Accessing other files in the util scope is easy<br>
 
Accessing other files in the util scope is easy<br>
addons/addonname/addonname/file.php is accessed like this:
+
addons/addonname/file.php is accessed like this:
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname-file&guild=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname-file
* SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname/file.html?guild=##
+
* SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname/file.html
 
Note that conf.php, install.def.php, and update_hook.php cannot be access this way
 
Note that conf.php, install.def.php, and update_hook.php cannot be access this way
  
Line 233: Line 283:
 
* Normal Link - http://[www.someurl.net]/roster/?p=scope-addonname-file
 
* Normal Link - http://[www.someurl.net]/roster/?p=scope-addonname-file
 
* SEO Link - http://[www.someurl.net]/roster/scope/addonname/file.html
 
* SEO Link - http://[www.someurl.net]/roster/scope/addonname/file.html
 +
{{Note|"file" is optional}}
  
 
The values explained
 
The values explained
* scope - One of three values; guild, char, util
+
* scope - One of five values; realm, guildless, guild, char, util
*: Guild (guild) is a page that uses guild information (guild=id# or guild=name@server can be appended to the url)
+
*: Realm (realm) - Page that uses realm information (realm=name is appended to the url)
*: Character (char) is a page that uses character information (member=id# or member=name@server must be appended to the url)
+
*: GuildLess (guildless) - Page that uses realm information for unguilded data (realm=name is appended to the url)
*: Utility (util) is a page that doesn't use either, or could use either, most of the Roster pages are utility pages (rostercp, update, credits)
+
*: 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
 
* addonname - The name of the AddOn you are accessing
 
* file - The file you are accessing
 
* file - The file you are accessing
Line 247: Line 300:
 
==Creating the Installer==
 
==Creating the Installer==
 
This installer requires a similar install file definition as DragonFly CMS, with
 
This installer requires a similar install file definition as DragonFly CMS, with
some important exeptions:
+
some important exceptions:
 
* SQL entries are the same as as passing it to mysql_query() using $installer->add_query($sqlstring)
 
* SQL entries are the same as as passing it to mysql_query() using $installer->add_query($sqlstring)
* No rollback data per query. Instead, call the BACKUP command for each table you want restored in case of an upgrade/uninstall failure.
+
* 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.
 
*: Any backup tables you create are automatically deleted in rollback.
* A lot of different required variables to be set.
+
* Different required variables to be set.
  
 
You should create a file called install.def.php with in it a class that is named identical to your AddOn's install directory name.<br>
 
You should create a file called 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.
 
This name will be referred to as your AddOn's basename.
  
 +
===Properties===
 
* var $active
 
* var $active
 
*: Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.
 
*: Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.
Line 272: Line 326:
  
 
* var $description
 
* var $description
*: String, used as a tooltip in serveral places.
+
*: String, a sort description of your AddOn.
  
 
* var $credits
 
* var $credits
Line 292: Line 346:
 
* upgrade($oldversion)
 
* upgrade($oldversion)
 
*: Here you can add all queries for an upgrade.
 
*: Here you can add all queries for an upgrade.
*:: $oldversion, the version you are upgrading from.
+
*:: <span style="color:darkred;">$oldversion</span>, the version you are upgrading from.
 
*: Return true on success, false on failure.
 
*: Return true on success, false on failure.
** 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.
+
{{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()
 
* uninstall()
Line 324: Line 378:
 
Note the title should be unique per AddOn.
 
Note the title should be unique per AddOn.
  
* $installer->add_menu_button($title, $scope, $url)
+
* $installer->add_menu_button($title, $scope, $url, %icon)
 
*: Adds a menu button. Parameters:
 
*: Adds a menu button. Parameters:
 
*: $title
 
*: $title
 
*:: The localization key for the menu button's title.
 
*:: The localization key for the menu button's title.
 
*: $scope
 
*: $scope
*:: The scope of the link ('util','guild','char')
+
*:: The scope of the link ('util','realm','guild','guildless','char')
 
*: $url
 
*: $url
 
*:: The url parameters this button should call the AddOn with
 
*:: The url parameters this button should call the AddOn with
 +
*: $icon
 +
*:: An icon to display in the button
  
* $installer->update_menu_button($title, $scope, $url)
+
* $installer->update_menu_button($title, $scope, $url, $icon)
 
*: Changes menu button. Parameters:
 
*: Changes menu button. Parameters:
 
*: $title
 
*: $title
 
*:: The localization key for the menu button's title.
 
*:: The localization key for the menu button's title.
 
*: $scope
 
*: $scope
*:: The scope of the link ('util','guild','char')
+
*:: The scope of the link ('util','realm','guild','guildless','char')
 
*: $url
 
*: $url
 
*:: The url parameters this button should call the AddOn with
 
*:: The url parameters this button should call the AddOn with
 +
*: $icon
 +
*:: An icon to display in the button
  
 
* $installer->remove_menu_button($title)
 
* $installer->remove_menu_button($title)
Line 351: Line 409:
 
Here is an example of an AddOn install file<br>
 
Here is an example of an AddOn install file<br>
 
From the "Keys" AddOn
 
From the "Keys" AddOn
 +
 +
You can find more examples in the addons/ folder in roster
 
<php><?php
 
<php><?php
 
/**
 
/**
Line 360: Line 420:
 
  * @copyright  2002-2007 WoWRoster.net
 
  * @copyright  2002-2007 WoWRoster.net
 
  * @license    http://creativecommons.org/licenses/by-nc-sa/2.5  Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
 
  * @license    http://creativecommons.org/licenses/by-nc-sa/2.5  Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
  * @version    SVN: $Id: pvp3.php 897 2007-05-06 00:35:11Z Zanix $
+
  * @version    SVN: $Id: install.def.php 897 2007-05-06 00:35:11Z Zanix $
 
  * @link      http://www.wowroster.net
 
  * @link      http://www.wowroster.net
 +
* @package    InstanceKeys
 +
* @subpackage Installer
 
*/
 
*/
  
Line 369: Line 431:
 
}
 
}
  
 +
/**
 +
* Installer Instance Keys Addon
 +
*
 +
* @package    InstanceKeys
 +
* @subpackage Installer
 +
*/
 
class keys
 
class keys
 
{
 
{
Line 379: Line 447:
  
 
var $fullname = 'Instance Keys';
 
var $fullname = 'Instance Keys';
var $description = 'Lists Dungeon keys for members';
+
var $description = 'Lists Azeroth Dungeon keys for Members';
 
var $credits = array(
 
var $credits = array(
 
array( "name"=> "WoWRoster Dev Team",
 
array( "name"=> "WoWRoster Dev Team",
Line 386: Line 454:
  
  
 +
/**
 +
* Install Function
 +
*
 +
* @return bool
 +
*/
 
function install()
 
function install()
 
{
 
{
Line 398: Line 471:
 
$installer->add_config("'1030','colorno','#ff0000','color','keys_conf'");
 
$installer->add_config("'1030','colorno','#ff0000','color','keys_conf'");
  
$installer->add_menu_button('keys','guild','');
+
$installer->add_menu_button('keys','guild');
 
return true;
 
return true;
 
}
 
}
  
 +
/**
 +
* Upgrade Function
 +
*
 +
* @param string $oldversion
 +
* @return bool
 +
*/
 
function upgrade($oldversion)
 
function upgrade($oldversion)
 
{
 
{
Line 408: Line 487:
 
}
 
}
  
 +
/**
 +
* Un-Install Function
 +
*
 +
* @return bool
 +
*/
 
function uninstall()
 
function uninstall()
 
{
 
{
Line 542: Line 626:
 
* The AddOn Framework automatically inserts the enUS locale strings into the deDE locale
 
* The AddOn Framework automatically inserts the enUS locale strings into the deDE locale
 
* This way, you only need to have enUS.php
 
* 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
+
* 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
  
  
Line 636: Line 720:
  
 
==CSS Styles==
 
==CSS Styles==
<css>/******************************
+
CSS style from the MembersList AddOn
  * $Id: default.css,v 1.7.2 2006/05/23 07:16:03 zanix Exp $
+
<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
 +
*/
  
/* EXAMPLE FILE ONLY FOR THE DUMMY PAGE */
+
.membersRowColor1 {
 +
background-color:#1F1E1D;
 +
}
  
.dummyStyle
+
.membersRowColor2 {
{
+
background-color:#2E2D2B;
border: 30px green solid;
+
 
}
 
}
</css>
 
  
I assume you know what css is...
+
.membersRowAltColor1 {
 +
background-color:#1F1E3D;
 +
}
  
 +
.membersRowAltColor2 {
 +
background-color:#2E2D4B;
 +
}</css>
  
 +
I assume you know what css is...
  
  
Line 656: Line 756:
  
 
==AddOn Update Hook==
 
==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
 +
 +
===Properties===
 +
The following variables are required in the update hook class
 +
 +
* var $messages
 +
*: String, any messages or output.
 +
 +
* var $data
 +
*: Array, Addon data object, recieved in constructor.
 +
*: This holds the addon's data from the database
 +
 +
* var $icon
 +
*: String, an icon to display for your AddOn in the AddOn management page in RosterCP
 +
*: Valid icons are from the Interface ImagePack
 +
 +
* var $files
 +
*: 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.
 +
 +
 +
 
<php><?php
 
<php><?php
 
/**
 
/**
Line 667: Line 790:
 
  * @version    SVN: $Id: update_hook.php 899 2007-05-06 10:16:36Z Zanix $
 
  * @version    SVN: $Id: update_hook.php 899 2007-05-06 10:16:36Z Zanix $
 
  * @link      http://www.wowroster.net
 
  * @link      http://www.wowroster.net
 +
* @package    AddOnName
 
*/
 
*/
  
Line 678: Line 802:
 
  * This MUST be the same name as the addon basename
 
  * This MUST be the same name as the addon basename
 
  */
 
  */
class recipeUpdate
+
class addonUpdate
 
{
 
{
 
var $messages = ''; // Update messages
 
var $messages = ''; // Update messages
Line 692: Line 816:
 
* @return recipe
 
* @return recipe
 
*/
 
*/
function recipeUpdate($data)
+
function addonUpdate($data)
 
{
 
{
 
$this->data = $data;
 
$this->data = $data;

Revision as of 23:49, 21 May 2007

WR.net

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

Contents


WoWRoster v1.8.0 AddOn Development

Readme Updated: 15:26, 6 May 2007 (PDT)

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



Certified WoWRoster AddOn

Certified WoWRoster AddOn

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


Requirements for Approval

Personal tools
Namespaces
Variants
Actions
WoWRoster
Preview Roster
Navigation
Toolbox