AddonSDK

From WoWRosterWiKi
(Difference between revisions)
Jump to: navigation, search
 
(44 intermediate revisions by 6 users not shown)
Line 1: Line 1:
 
__NOEDITSECTION__
 
__NOEDITSECTION__
{{Disclaimer}}
+
{{Disclaimer|NoLang}}
 
{{MainMenu|Roster}}
 
{{MainMenu|Roster}}
  
=WoWRoster v1.8.0b AddOn Development=
+
==WoWRoster v2.0.0 AddOn Development==
Updated: 13:34, 12 August 2007 (PDT)
+
Updated: 18:18, 15 June 2008 (CDT)
 
+
This document is being revised as 1.8 goes through development<br>
+
Keep checking back for changes and additions
+
  
 
==Changes==
 
==Changes==
* [[User:Zanix|Zanix]] 13:34, 12 August 2007 (PDT)
+
See [[Talk:AddonSDK|Discussion]]
*: Added information about the new template parser
+
 
+
* [[User:Anaxent|Anaxent]] 12:16, 12 August 2007 (PDT)
+
*: More info on search class
+
 
+
* [[User:Anaxent|Anaxent]] 22:25, 25 July 2007 (PDT)
+
*: Added beginnings of search class for Addons
+
 
+
* [[User:Zanix|Zanix]] 20:59, 25 July 2007 (PDT)
+
*: Guildless Scope removed
+
*: New addon variables - $addon['url'], $addon['url_full'], $addon['url_path'], $addon['image_full'], $addon['image_path']
+
*: Clarified $roster->data variable
+
*: Updated messagebox(), border(), readbleDate()
+
*: New functions stripslash_array(), aprint(), socketColorEn()
+
*: Added beginnings of search class for Addons
+
 
+
*  [[User:Zanix|Zanix]] 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
+
  
 
__TOC__
 
__TOC__
Line 40: Line 18:
  
 
Thanks to:
 
Thanks to:
http://www.wowroster.com<br />
+
wowroster com (no longer online)<br />
 
And Everyone involved in the project.
 
And Everyone involved in the project.
  
  
'''Download the [http://www.wowroster.net/Downloads/details/id=32.html Roster AddOnSDK]'''
+
'''Download the [http://www.wowroster.net/downloads/?id=32 Roster AddOnSDK]'''<br>
  
  
Line 62: Line 40:
 
* Create AddOns with SQL Debug Output, Debug Mode, and SQL Window enabled in [[Roster:CP|RosterCP]]
 
* 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
 
** 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)
+
* No funky text (such as BOM characters)
 
*: (ie: strange characters appearing on top of the roster's menu)
 
*: (ie: strange characters appearing on top of the roster's menu)
 
* Valid XHTML 1.0 Transitional - http://validator.w3.org
 
* Valid XHTML 1.0 Transitional - http://validator.w3.org
* Proper use of the DB layer - <span style="color:maroon;">$roster->db</span>
+
* Proper use of the DB layer - [[Roster:FunctionsOverview#.24roster-.3Edb|$roster->db]]
 
* Roster main files are not edited
 
* 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
 
* Roster main database tables are not edited, unless you provide a clean way to revert the data in your uninstall
Line 81: Line 59:
 
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)
  
<div style="margin:5px 0 5px 0;">
+
{{Warning|Important|DO NOT use php short tags in your php files as stated in the [[CodingStandards|WoWRoster Coding Standards]]<br>Use the normal "long tag" as short tags can break page rendering with php "short_tags" set to "Off"<br><br>'''NO!''' <code><?</code><br>'''YES''' <code><?php</code><br>'''NO!''' <code><nowiki><?=$var; ?></nowiki></code><br>'''YES''' <code><nowiki><?php echo $var; ?></nowiki></code>}}
{| 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==
 
==Changes Since 1.7.3==
* All AddOns need to be installed using an install definition file inc/install.def.php.
+
* All AddOns need to be installed using an install definition file [[#Creating_the_Installer|inc/install.def.php]].
 
* During install, database tables, graphical configuration, menu buttons, and update hooks can be registered with the main framework.
 
* 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.
 
* menu.php file is no longer required.
 
* conf.php is still used because there may be more to initialize than just settings.
 
* 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
 
** conf.php has been moved to addonname/inc/conf.php
* Several variables in addon.php, most notably $addonDir, have changed names.
+
* Several variables, most notably $addonDir, have changed names.
 
* localization.php is no longer used.
 
* 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
+
** 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:
 
* Configuration from database is automatically added. Addons are initialized in this order:
 
** Addon registration record
 
** Addon registration record
Line 117: Line 81:
 
* The addon is called differently now.
 
* The addon is called differently now.
 
** Details are below.
 
** 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.
 
* You do not know the basename at design time.
 
** Please use the $addon['basename'] variable for this at all times.
 
** Please use the $addon['basename'] variable for this at all times.
* On lua updates, the addon's inc/update_hook.php is included once.
+
* On lua updates, the addon's [[#AddOn_Update_Hook|inc/update_hook.php]] is included once.
 
** Details for the new update hook structure is below
 
** Details for the new update hook structure is below
 
* Menu buttons are created in the database using installer functions
 
* Menu buttons are created in the database using installer functions
Line 127: Line 96:
 
** lib/roster.php: Roster global 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
 
*** 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
+
** 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
 
** lib/template.php
*** Template parser based on phpbb, EQDkp, and DragonFly
+
*** Template parser based on DragonFly
  
  
Line 140: Line 110:
 
# Do not have to connect to Roster's database
 
# Do not have to connect to Roster's database
 
# Do not have to include your inc/conf.php
 
# 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!
+
# AddOn files: inc/conf.php, [[#CSS_Styles|style.css]], [[#AddOn_Update_Hook|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
 
#: Even additional locale files are optional, enUS.php is the default locale, and is required if you have locale files
  
Line 147: Line 117:
 
===What it does===
 
===What it does===
 
# Includes all Roster config variables for you to use (<span style="color:maroon;">$roster</span>->config)
 
# 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 SQL functions for your use ([[Roster:FunctionsOverview#.24roster-.3Edb|$roster->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 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
 
# Includes all Roster css styles
Line 193: Line 163:
 
       |_ index.php
 
       |_ index.php
 
       |_ somefile.php
 
       |_ somefile.php
 +
      |_ style.css
 
       |_ util.php
 
       |_ util.php
 
</pre>
 
</pre>
Line 206: Line 177:
 
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-addonname-file
 
* 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
 
* SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/addonname/file.html
{{Note|The File parameter is optional}}
+
{{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 223: Line 194:
  
  
====char Folder====
+
====char Folder (character scope)====
 
Files for use in the Character scope<br>
 
Files for use in the Character scope<br>
 
Data for the requested character is passed to the AddOn<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
+
If a=c:## 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
+
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&member=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&a=c:##
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=name@realm
+
* 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/member=##.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/a=c:##.html
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=name@realm.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<br>
 
Accessing other files in the char scope is easy<br>
 
addons/addonname/addonname/char/file.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-addonname-file&member=##
+
* 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/member=##.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/file/a=c:##.html
  
  
  
====guild Folder====
+
====guild Folder (guild scope)====
 
Files for use in the Guild scope<br>
 
Files for use in the Guild scope<br>
 
Data for the requested guild is passed to the AddOn<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 a=g: 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
 
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
+
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&guild=##
+
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&a=g:##
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=name@realm
+
* 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/guild=##.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/a=g:##.html
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=name@realm.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<br>
 
Accessing other files in the guild scope is easy<br>
 
addons/addonname/guild/file.php is accessed like this:
 
addons/addonname/guild/file.php is accessed like this:
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname-file&guild=##
+
* 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/guild=##.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/file/a=g:##.html
  
  
  
 
====inc Folder====
 
====inc Folder====
This folder houses special files not meant for direct access by the AddOn Framework<br>
+
This folder houses special files not meant for direct access by the AddOn Framework
These files are conf.php, install.def.php, search.inc, and update_hook.php<br>
+
 
You can also use this folder for lib, library, and/or functions files
+
* conf.php - This is included before any other addon file, any initialization can be done here
 +
* [[#Creating_the_Installer|install.def.php]] - The AddOn's install/upgrade/uninstall definition file
 +
* [[#Creating_the_Search_Class|search.inc.php]] - Search plug-in for the Roster search page
 +
* [[#AddOn_Update_Hook|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
 
Place any files here that you do not or should not be accessed directly by the AddOn Framework
Line 277: Line 254:
  
  
====realm Folder====
+
====realm Folder (realm scope)====
 
Files for use in the Realm scope<br>
 
Files for use in the Realm scope<br>
 
Data for the requested realm is passed to the AddOn<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 a=r: 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
 
If the realm does not exist or if there is no data for this realm, an error message will display
  
realm= can be text
+
a=r: can be text
  
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&realm=name
+
* 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/realm=name.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/a=r:rc-name.html
  
 
Accessing other files in the realm scope is easy<br>
 
Accessing other files in the realm scope is easy<br>
 
addons/addonname/realm/file.php is accessed like this:
 
addons/addonname/realm/file.php is accessed like this:
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=realm-addonname-file&realm=name
+
* 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/realm=name.html
+
* SEO Link - http://[www.someurl.net]/roster/trunk/realm/addonname/file/a=r:rc-name.html
  
  
  
====Other Files and the util Scope====
+
====The util Scope====
 
Files not in these folders are considered under the util scope<br>
 
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
 
This scope is not restricted if there is no guild or character information and can be accessed before data is in the database
Line 309: Line 286:
 
* SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname/file.html
 
* 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
+
 
 +
 
 +
====Other Files====
 
* index.php - The main file for the util scope
 
* 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
 
* [[#CSS_Styles|style.css]] - A custom css style for the AddOn
* [[#AddOn_Update_Hook|inc/update_hook.php]] - Update Hook file
 
  
  
Line 333: Line 310:
 
The values explained
 
The values explained
 
* scope - One of five values; realm, guild, char, util
 
* scope - One of five values; realm, guild, char, util
*: Realm (realm) - Page that uses realm information (realm=name is appended to the url)
+
*: Realm (realm) - Page that uses realm information (a=r:rc-name is appended to the url)
*: Guild (guild) - Page that uses guild information (guild=id# or guild=name@server 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 (member=id# or member=name@server must be 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 pages (rostercp, update, credits, search)
+
*: 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
 
* addonname - The name of the AddOn you are accessing
 
* file - The file you are accessing
 
* file - The file you are accessing
 +
*: If 'file' does not exist, the AddOn Framework defaults the file to index.php
  
  
Line 350: Line 328:
 
* Different required variables to be set.
 
* 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>
+
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.
This name will be referred to as your AddOn's basename.
+
{{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.
  
  
Line 362: Line 341:
 
*: String, the current version of your AddOn.
 
*: String, the current version of your AddOn.
 
*: Needs to be compatible with php's version_compare().
 
*: 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.
+
*: Should be incremented on every update. So you know what version someone is running.
  
 
* var <span style="color:maroon;">$icon</span>
 
* var <span style="color:maroon;">$icon</span>
 
*: String, an icon to display for your AddOn in the AddOn management page in RosterCP
 
*: String, an icon to display for your AddOn in the AddOn management page in RosterCP
*: Valid icons are from the Interface ImagePack
+
*: 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 <span style="color:maroon;">$fullname</span>
 
* var <span style="color:maroon;">$fullname</span>
 
*: String, the full name of the AddOn for display.
 
*: String, the full name of the AddOn for display.
 +
*: This can either be literal or reference a locale key.
  
 
* var <span style="color:maroon;">$description</span>
 
* var <span style="color:maroon;">$description</span>
 
*: String, a sort description of your AddOn.
 
*: String, a sort description of your AddOn.
 +
*: This can either be literal or reference a locale key.
 +
 +
* var <span style="color:maroon;">$wrnet_id</span>
 +
*: 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/?id=20
 +
*::: 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 <span style="color:maroon;">$credits</span>
 
* var <span style="color:maroon;">$credits</span>
Line 385: Line 378:
  
  
===Methods===
+
===AddOn Install Class Methods===
 
* install()
 
* install()
 
*: Here you can add all queries for a fresh install.
 
*: Here you can add all queries for a fresh install.
Line 395: Line 388:
 
*:: <span style="color:maroon;">$oldversion</span>, the version you are upgrading from.
 
*:: <span style="color:maroon;">$oldversion</span>, the version you are upgrading from.
 
*: Return true on success, false on failure.
 
*: 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()
 
* uninstall()
Line 404: Line 396:
  
  
===Adding Queries===
+
===Queries===
 
Queries are added to the install using the <span style="color:maroon;">$installer</span> methods.
 
Queries are added to the install using the <span style="color:maroon;">$installer</span> methods.
 +
 +
* <span style="color:maroon;">$installer</span>->create_table(<span style="color:maroon;">$tablename</span>,<span style="color:maroon;">$tabledata</span>);
 +
*: 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
 +
 +
* <span style="color:maroon;">$installer</span>->drop_table(<span style="color:maroon;">$tablename</span>);
 +
*: Drop a table from the Roster database
 +
*: This isn't required for dropping a table, but it sure is handy
  
 
* <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>);
 
* <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>);
Line 415: Line 416:
 
* <span style="color:maroon;">$installer</span>->add_drop(<span style="color:maroon;">$table</span>)
 
* <span style="color:maroon;">$installer</span>->add_drop(<span style="color:maroon;">$table</span>)
 
*: Have a table be dropped on rollback
 
*: 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
  
 
* <span style="color:maroon;">$installer</span>->add_config(<span style="color:maroon;">$sqlstring</span>);
 
* <span style="color:maroon;">$installer</span>->add_config(<span style="color:maroon;">$sqlstring</span>);
 
*: Add config sql to `roster_addon_config` table
 
*: Add config sql to `roster_addon_config` table
 
*: Format is "'id','config_name','config_value','form_type','config_type'"
 
*: 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
+
 
 +
* <span style="color:maroon;">$installer</span>->update_config(<span style="color:maroon;">$id</span>, <span style="color:maroon;">$sqlstring</span>);
 +
*: Modify an existing config value
 +
*: <span style="color:maroon;">$id</span> is the id of the config value
 +
*: <span style="color:maroon;">$sqlstring</span> is what would be inside <span style="color:green;">"UPDATE `roster_addon_config` SET <span style="color:maroon;">$sqlstring</span> WHERE `config_id` = '<span style="color:maroon;">$id</span>';"</span>
 +
* <span style="color:maroon;">$installer</span>->remove_config(<span style="color:maroon;">$id</span>);
 +
*: Remove an existing config value
 +
*: <span style="color:maroon;">$id</span> is the id of the config value
 +
 
 +
* <span style="color:maroon;">$installer</span>->remove_all_config();
 +
*: Removes all the config data for the addon
  
  
  
 
===Creating/Editing Menu Entries===
 
===Creating/Editing Menu Entries===
There are 3 separate functions for this.<br>
+
There are 5 functions for creating, changing, and editing menu entries.<br>
Note the title should be unique per AddOn.
+
Note the menu button titles should be unique per AddOn.<br>
 +
Using your basename in the key will work fine.
 +
 
 +
* <span style="color:maroon;">$installer</span>->add_menu_pane(<span style="color:maroon;">$name</span>)
 +
*: Adds a menu pane to insert menu entries into
 +
*:: 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
 +
 
 +
* <span style="color:maroon;">$installer</span>->remove_menu_pane(<span style="color:maroon;">$name</span>)
 +
*: Removes a menu pane
 +
*:: you cannot remove a roster made pane ('util','realm','guild','char')
  
 
* <span style="color:maroon;">$installer</span>->add_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
 
* <span style="color:maroon;">$installer</span>->add_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
Line 437: Line 464:
 
*: <span style="color:maroon;">$icon</span>
 
*: <span style="color:maroon;">$icon</span>
 
*:: An icon to display in the button
 
*:: 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.
  
* <span style="color:maroon;">$installer</span>->update_menu_button($title, $scope, $url, $icon)
+
* <span style="color:maroon;">$installer</span>->update_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
 
*: Changes menu button. Parameters:
 
*: Changes menu button. Parameters:
 
*: <span style="color:maroon;">$title</span>
 
*: <span style="color:maroon;">$title</span>
Line 448: Line 479:
 
*: <span style="color:maroon;">$icon</span>
 
*: <span style="color:maroon;">$icon</span>
 
*:: An icon to display in the button
 
*:: 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.
  
* <span style="color:maroon;">$installer</span>->remove_menu_button($title)
+
* <span style="color:maroon;">$installer</span>->remove_menu_button(<span style="color:maroon;">$title</span>)
 
*: Removes a menu button. Parameters:
 
*: Removes a menu button. Parameters:
 
*: <span style="color:maroon;">$title</span>
 
*: <span style="color:maroon;">$title</span>
 
*:: The localization key for the menu button's title.
 
*:: The localization key for the menu button's title.
 +
 +
* <span style="color:maroon;">$installer</span>->remove_all_menu_button()
 +
*: Removes all the menu buttons for the addon.
 +
 +
 +
 +
===Other Installer Methods===
 +
* <span style="color:maroon;">$installer</span>->table(<span style="color:maroon;">$table</span>, <span style="color:maroon;">$backup</span>=<span style="color:blue;">false</span>)
 +
*: 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'
 +
 +
* <span style="color:maroon;">$installer</span>->seterrors(<span style="color:maroon;">$string</span>)
 +
*: Set an error message to be displayed.
 +
 +
* <span style="color:maroon;">$installer</span>->setmessages(<span style="color:maroon;">$string</span>)
 +
*: Set a message to be displayed.
  
  
Line 458: Line 510:
 
===Example File===
 
===Example File===
 
Here is an example of an AddOn install file<br>
 
Here is an example of an AddOn install file<br>
From the "Keys" AddOn
+
This shows most of the methods that can be used in an installer
  
 
You can find more examples in the addons/ folder in roster
 
You can find more examples in the addons/ folder in roster
Line 472: Line 524:
 
  * @version    SVN: $Id: install.def.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
+
  * @package    SomeAddon
 
  * @subpackage Installer
 
  * @subpackage Installer
 
*/
 
*/
  
if ( !defined('ROSTER_INSTALLED') )
+
if ( !defined('IN_ROSTER') )
 
{
 
{
 
     exit('Detected invalid access to this file!');
 
     exit('Detected invalid access to this file!');
Line 482: Line 534:
  
 
/**
 
/**
  * Installer Instance Keys Addon
+
  * Installer SomeAddon
 
  *
 
  *
 
  * @package    InstanceKeys
 
  * @package    InstanceKeys
 
  * @subpackage Installer
 
  * @subpackage Installer
 
  */
 
  */
class keys
+
class SomeAddonInstall
 
{
 
{
 
var $active = true;
 
var $active = true;
 
var $icon = 'inv_misc_key_06';
 
var $icon = 'inv_misc_key_06';
  
var $upgrades = array(); // There are no previous versions to upgrade from
+
var $version = '2.0.0.0';
 +
var $wrnet_id = 0;
  
var $version = '1.8.0.0';
+
var $fullname = 'some_addon';
 
+
var $description = 'some_addon_desc';
var $fullname = 'Instance Keys';
+
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 515: Line 566:
 
// Master and menu entries
 
// Master and menu entries
 
$installer->add_config("'1','startpage','keys_conf','display','master'");
 
$installer->add_config("'1','startpage','keys_conf','display','master'");
$installer->add_config("'110','keys_conf',NULL,'blockframe','menu'");
+
$installer->add_config("'110','some_addon_conf',NULL,'blockframe','menu'");
  
$installer->add_config("'1010','colorcmp','#00ff00','color','keys_conf'");
+
$installer->add_config("'1010','colorcmp','#00ff00','color','some_addon_conf'");
$installer->add_config("'1020','colorcur','#ffd700','color','keys_conf'");
+
$installer->add_config("'1020','colorcur','#ffd700','color','some_addon_conf'");
$installer->add_config("'1030','colorno','#ff0000','color','keys_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`)");
  
$installer->add_menu_button('keys','guild');
 
 
return true;
 
return true;
 
}
 
}
Line 533: Line 592:
 
function upgrade($oldversion)
 
function upgrade($oldversion)
 
{
 
{
// Nothing to upgrade from yet
+
global $installer;
return false;
+
 
 +
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;
 
}
 
}
  
Line 548: Line 623:
 
$installer->remove_all_config();
 
$installer->remove_all_config();
  
$installer->remove_menu_button('keys');
+
$installer->drop_table($installer->table('some_table'));
 +
 
 +
$installer->remove_all_menu_button();
 
return true;
 
return true;
 
}
 
}
Line 556: Line 633:
  
 
==Creating the Search Class==
 
==Creating the Search Class==
===Properties===
+
Get customizable search results on the Roster search page for your AddOn<br>
 +
AddOn search classes are basically just SQL statements with some added functionality for the Search Framework<br>
 +
The search class can search by using SQL and process the data in a readable format for display<br>
 +
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 <span style="color:maroon;">$options</span>
 
* var <span style="color:maroon;">$options</span>
*: Used to to add advanced options to the search page
+
*: array - Used to to add advanced options to the search page
  
 
* var <span style="color:maroon;">$result</span>
 
* var <span style="color:maroon;">$result</span>
*: Search array
+
*: array - Search array
  
 
* var <span style="color:maroon;">$result_count</span>
 
* var <span style="color:maroon;">$result_count</span>
*: Counter for results display
+
*: int - Counter for results display
  
* var <span style="color:maroon;">$link_next</span>
+
* var <span style="color:maroon;">$start_search</span>
*: Used to create a url to the next page of results
+
*: int - Time search starts
  
* var <span style="color:maroon;">$link_prev</span>
+
* var <span style="color:maroon;">$stop_search</span>
*: Used to create a url to the previous page of results
+
*: int - Time search stops
 +
 
 +
* var <span style="color:maroon;">$time_search</span>
 +
*: int - Time spent on search
 +
 
 +
* var <span style="color:maroon;">$open_table</span>
 +
*: string - Insert a custom header in the search results
 +
 
 +
* var <span style="color:maroon;">$close_table</span>
 +
*: string - Insert a custom footer in the search results
 +
 
 +
* var <span style="color:maroon;">$search_url</span>
 +
*: string - Additional data to insert into the prev/next url links
  
 
* var <span style="color:maroon;">$data</span>
 
* var <span style="color:maroon;">$data</span>
*: An array that holds all of the addons data
+
*: array - An array that holds all of the addons data, including config
 +
*: The search framework automatically populates this property
  
* var <span style="color:maroon;">$page</span>
 
*: Counter for page number
 
  
* var <span style="color:maroon;">$limit</span>
+
====Methods====
*: Counter for the number of results that can be displayed per page
+
=====Constructor=====
 +
Used to set up data needed for your search class
  
* var <span style="color:maroon;">$sql_query</span>
+
Use this to populate $this->open_table, $this->close_table, and/or $this->options
*: -
+
  
* var <span style="color:maroon;">$the_query</span>
+
=====search=====
*: -
+
search( $search , $limit=10 , $page=0 )<br>
 +
The meat and potatoes of your search class<br>
 +
Perform the SQL and process any returned data in this class method
  
* var <span style="color:maroon;">$url_query</span>
+
=====add_result=====
*: Urlencoded query
+
add_result( $resultarray )<br>
 +
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<br>
 +
This data must be passed to $this->add_result($item); to show up on the search results page
  
 
* var <span style="color:maroon;">$item</span>['results_header']
 
* var <span style="color:maroon;">$item</span>['results_header']
*: When this variable is used it will add a header above each result with in that addon search
+
*: string - Adds a header before the result row (outside the <tr>) within that addon search
 +
 
 +
* var <span style="color:maroon;">$item</span>['results_footer']
 +
*: string - Adds a footer after the result row (outside the </tr>) within that addon search
  
 
* var <span style="color:maroon;">$item</span>['html']
 
* var <span style="color:maroon;">$item</span>['html']
*: When used this variable allows you to display your own formated html code which over rides any predefined search display
+
*: 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 <u>not</u> set}}
 +
* var <span style="color:maroon;">$item</span>['header']
 +
*: Adds a header before the result cell (inside the <tr><td>) within that addon search
  
 
* var <span style="color:maroon;">$item</span>['author']
 
* var <span style="color:maroon;">$item</span>['author']
*: Used to display the author of a post/update/upload
+
*: string - Used to display the author of a post/update/upload
  
 
* var <span style="color:maroon;">$item</span>['date']
 
* var <span style="color:maroon;">$item</span>['date']
*. var that will print the date
+
*: string - var that will print the date
  
 
* var <span style="color:maroon;">$item</span>['url']
 
* var <span style="color:maroon;">$item</span>['url']
*: Variable used to create a makelink() to the results addons home page
+
*: string - Variable used to create a makelink() to the results addons home page
  
* var <span style="color:maroon;">$result</span>['title']
+
* var <span style="color:maroon;">$item</span>['title']
*: Displays the title of the addon  
+
*: string - Displays the title of the addon
  
* var <span style="color:maroon;">$result</span>['short_text']
+
* var <span style="color:maroon;">$item</span>['short_text']
*: Used to give a short description of the result
+
*: string - Short description of the result
  
* var <span style="color:maroon;">$result</span>['more_text']
+
* var <span style="color:maroon;">$item</span>['more_text']
*: Used to create a secondary link per result
+
*: string - Secondary link per result
  
* var <span style="color:maroon;">$result</span>['footer']
+
* var <span style="color:maroon;">$item</span>['footer']
*: If desired allows each addon result to have a custom footer
+
*: Adds a footer after the result cell (inside the </td></tr>) within that addon search
  
* var <span style="color:maroon;">$result</span>['results_footer']
 
*: Used to create a footer for the addon results overall footer
 
  
 +
===Search Framework Variables===
 +
* var <span style="color:maroon;">$page</span>
 +
*: int - Counter for page number
 +
 +
* var <span style="color:maroon;">$limit</span>
 +
*: int - Counter for the number of results that can be displayed per page
 +
 +
* var <span style="color:maroon;">$query</span>
 +
*: string - Search string passed
 +
 +
* var <span style="color:maroon;">$url_query</span>
 +
*: string - Urlencoded $query
  
  
 
===Example File===
 
===Example File===
Here is an example of an AddOn install file<br>
+
Here is an example of an AddOn search.inc file<br>
 
From the "News" AddOn
 
From the "News" AddOn
  
You can find more examples in the addons/ folder in roster
+
You can find more examples in other AddOns such as memberslist or news
 
<php><?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: search.inc.php 1664 2008-02-14 04:24:52Z Zanix $
 +
* @link      http://www.wowroster.net
 +
* @package    News
 +
* @subpackage Search
 +
*/
  
class news_search
+
if( !defined('IN_ROSTER') )
 +
{
 +
    exit('Detected invalid access to this file!');
 +
}
 +
 
 +
/**
 +
* News Search
 +
*
 +
* @package    News
 +
* @subpackage Search
 +
*/
 +
class newsSearch
 
{
 
{
 
var $options;
 
var $options;
 
var $result = array();
 
var $result = array();
 
var $result_count = 0;
 
var $result_count = 0;
var $link_next;
+
var $start_search;
var $link_prev;
+
var $stop_search;
var $data = array(); // Addon data
+
var $time_search;
 +
var $open_table;
 +
var $close_table;
 +
var $search_url;
 +
var $data = array();   // Addon data
  
 
+
function search( $search , $limit=10 , $page=0 )
function search( $search , $url_search , $limit=10 , $page=0 )
+
 
{
 
{
 
global $roster;
 
global $roster;
Line 645: Line 796:
 
$first = $page*$limit;
 
$first = $page*$limit;
  
$q = "SELECT `news`.`news_id`, `news`.`author`, `news`.`title`, `news`.`content`, `news`.`html`, "
+
$sql = "SELECT `news`.`news_id`, `news`.`author`, `news`.`title`, `news`.`content`, `news`.`html`, "
. "DATE_FORMAT(  DATE_ADD(`news`.`date`, INTERVAL "  
+
. "DATE_FORMAT(  DATE_ADD(`news`.`date`, INTERVAL " . $roster->config['localtimeoffset'] . " HOUR ), '" . $roster->locale->act['timeformat'] . "' ) AS 'date_format', "
                        . $roster->config['localtimeoffset'] . " HOUR ), '" . $roster->locale->act['timeformat'] . "' ) AS 'date_format', "
+
. "COUNT(`comments`.`comment_id`) comm_count "
. "COUNT(`comments`.`comment_id`) comm_count "
+
. "FROM `" . $roster->db->table('news','news') . "` news "
. "FROM `" . $roster->db->table('news','news') . "` news "
+
. "LEFT JOIN `" . $roster->db->table('comments','news') . "` comments USING (`news_id`) "
. "LEFT JOIN `" . $roster->db->table('comments','news') . "` comments USING (`news_id`) "
+
. "WHERE `news`.`news_id` LIKE '%$search%' "
. "WHERE `news`.`news_id` LIKE '%$search%' "
+
. "OR `news`.`author` LIKE '%$search%' "
. "OR `news`.`author` LIKE '%$search%' "
+
. "OR `news`.`date` LIKE '%$search%' "
. "OR `news`.`date` LIKE '%$search%' "
+
. "OR `news`.`title` LIKE '%$search%' "
. "OR `news`.`title` LIKE '%$search%' "
+
. "OR `news`.`content` LIKE '%$search%' "
. "OR `news`.`content` LIKE '%$search%' "
+
. "GROUP BY `news`.`news_id` "
. "GROUP BY `news`.`news_id` "
+
. ( $limit > 0 ? " LIMIT $first," . $limit : '' ) . ';';
. "LIMIT $first," . ($limit+1) .";";
+
 
 +
//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;
  
$result = $roster->db->query($q);
 
 
$nrows = $roster->db->num_rows($result);
 
$nrows = $roster->db->num_rows($result);
  
$x = ($limit > $nrows) ? $nrows : $limit;
+
$x = ($limit > $nrows) ? $nrows : ($limit > 0 ? $limit : $nrows);
 
if( $nrows > 0 )
 
if( $nrows > 0 )
 
{
 
{
Line 696: Line 853:
 
$item['short_text'] = implode(' ',$array);
 
$item['short_text'] = implode(' ',$array);
  
$item['footer'] = ($comments == 0?'No':$comments) . ' comment' . ($comments == 1?'':'s');
+
$item['footer'] = ($comments == 0 ? 'No' : $comments) . ' comment' . ($comments == 1 ? '' : 's');
  
 
$this->add_result($item);
 
$this->add_result($item);
Line 703: Line 860:
 
}
 
}
 
}
 
}
 
+
$roster->db->free_result($result);
if( $page > 0 )
+
{
+
$this->link_prev = '<a href="' . makelink('search&amp;page=' . ($page-1) . '&amp;search=' . $url_search . '&amp;s_addon='
+
. $this->data['basename']) . '"><strong>' . $roster->locale->act['search_previous_matches'] . $this->data['basename'] . '</strong></a>';
+
}
+
if( $nrows > $limit )
+
{
+
$this->link_next = '<a href="' . makelink('search&amp;page=' . ($page+1) . '&amp;search=' . $url_search . '&amp;s_addon='
+
. $this->data['basename']) . '"><strong> ' . $roster->locale->act['search_next_matches'] . $this->data['basename'] . '</strong></a>';
+
}
+
 
}
 
}
  
Line 720: Line 867:
 
$this->result[$this->result_count++] = $resultarray;
 
$this->result[$this->result_count++] = $resultarray;
 
}
 
}
}
+
}</php>
</php>
+
  
  
Line 735: Line 881:
  
 
===Menu Bar Items===
 
===Menu Bar Items===
 +
* display:
 +
*: Sets the first page that will be displayed when you first select the addon for configuration.
 +
*: <span style="color:maroon;">$installer</span>->add_config("'1','startpage','config_name','display','master'")
 +
 
* page, pageframe, pagehide, blockframe, blockhide:
 
* page, pageframe, pagehide, blockframe, blockhide:
 
*: A page of options that gets selected with javascript
 
*: 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("'110','config_name',NULL,'blockframe','menu'")
*: <span style="color:maroon;">$installer</span>->add_config("'150', 'config_name', NULL, 'page{1', 'menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'150', 'config_name2', NULL, 'page{1', 'menu'")
  
 
* link
 
* link
Line 749: Line 899:
  
 
* makelink
 
* makelink
*: Passes this through Roster's makelink() function to generate a correct link to another page in Roster.
+
*: Passes this through Roster's [[Roster:FunctionsOverview#makelink|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'")
 
*: <span style="color:maroon;">$installer</span>->add_config("120,'config_name','link_value','makelink','menu'")
  
 
* makenewlink
 
* makenewlink
*: Same as makelink, except it opens a new browser window.
+
*: Same as [[Roster:FunctionsOverview#makelink|makelink()]], except it opens a new browser window.
 
*: <span style="color:maroon;">$installer</span>->add_config("180,'config_name','link_value','makenewlink','menu'")
 
*: <span style="color:maroon;">$installer</span>->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===
 
===Options Blocks===
Line 868: Line 1,019:
  
 
===Example File===
 
===Example File===
Example from the PvPLog Roster AddOn<br>
+
Example from the MembersList Roster AddOn<br>
addons/questlist/locale/deDE.php
+
addons/memberslist/locale/deDE.php
 +
{{Note|This is only part of the file}}
 
<php><?php
 
<php><?php
 
/**
 
/**
Line 879: Line 1,031:
 
  * @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: deDE.php 899 2007-05-06 10:16:36Z Zanix $
+
  * @version    SVN: $Id: deDE.php 1523 2007-12-13 12:24:31Z pleegwat $
 
  * @link      http://www.wowroster.net
 
  * @link      http://www.wowroster.net
 +
* @package    MembersList
 +
* @subpackage Locale
 
*/
 
*/
  
$lang['bglog']='BG &Uuml;bersicht';
+
// -[ deDE Localization ]-
$lang['pvplog']='PvP &Uuml;bersicht';
+
 
$lang['duellog']='Duell &Uuml;bersicht';
+
// Installer names
$lang['duelsummary']='Duell Summary';
+
$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['totalwins']='Gewinne total';
+
$lang['skill_level'] = 'Skill level';
$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
+
// Last Online words
$lang['alterac_valley']='Alteractal';
+
$lang['online_at_update']       = 'Online bei Update';
$lang['arathi_basin']='Arathibecken';
+
$lang['second']                 = 'vor %s Sekunde';
$lang['warsong_gulch']='Kriegshymnenschlucht';
+
$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['world_pvp']='Welt-PvP';
+
$lang['armor_tooltip'] = 'Verringert den erlittenen körperlichen Schaden um %1$s%%';
$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['motd']                   = 'MOTD';
$lang['losses']='Verluste';
+
$lang['accounts']               = 'Accounts';
$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
+
// Configuration
$lang['guildwins'] = 'Wins by Guild';
+
$lang['memberslist_config'] = 'Gehe zur Mitgliederliste-Konfiguration';
$lang['guildlosses'] = 'Losses by Guild';
+
$lang['memberslist_config_page']= 'Mitgliederliste-Konfiguration';
$lang['enemywins'] = 'Wins by Enemy';
+
$lang['documentation'] = 'Dokumentation';
$lang['enemylosses'] = 'Losses by Enemy';
+
$lang['uninstall'] = 'Uninstall';
$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";
+
// Page names
$lang['admin']['minPvPLogver'] = "Min PvPLog version|Minimum PvPLog Version zum Upload";
+
$lang['admin']['display']       = 'Anzeige|Konfiguriert die Anzeigeoptionen für die Mitgliederliste.';
</php>
+
$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';</php>
  
  
  
 
==CSS Styles==
 
==CSS Styles==
CSS style from the MembersList AddOn
+
CSS style from the MembersList AddOn<br>
 +
addons/memberslist/style.css
 
<css>/**
 
<css>/**
 
  * WoWRoster.net WoWRoster
 
  * WoWRoster.net WoWRoster
Line 990: Line 1,168:
 
===Getting Started===
 
===Getting Started===
 
Create a folder in roster/templates/default/ with your AddOn's basename<br>
 
Create a folder in roster/templates/default/ with your AddOn's basename<br>
 +
Or create a templates/ folder in your addon folder<br>
 
This folder will hold all the templates for your AddOn
 
This folder will hold all the templates for your AddOn
  
Line 1,009: Line 1,188:
 
What happens here is that we are making and setting template variables.<br>
 
What happens here is that we are making and setting template variables.<br>
 
Notice how the variables in available to the template are much simpler than the php variables<br>
 
Notice how the variables in available to the template are much simpler than the php variables<br>
'L_POSTEDBY' as opposed to $roster->locale->act['posted_by']
+
'L_POSTEDBY' as opposed to <span style="color:maroon;">$roster</span>->locale->act['posted_by']
  
  
Line 1,031: Line 1,210:
 
'U_EDIT'    => makelink('util-news-edit&amp;id=' . $news['news_id']),
 
'U_EDIT'    => makelink('util-news-edit&amp;id=' . $news['news_id']),
  
'L_COMMENT' => ($news['comm_count'] != 1 ? sprintf($roster->locale->act['n_comments'],$news['comm_count']) : sprintf($roster->locale->act['n_comment'],$news['comm_count'])),
+
'L_COMMENT' => ($news['comm_count'] != 1 ?
 +
sprintf($roster->locale->act['n_comments'],$news['comm_count']) :
 +
sprintf($roster->locale->act['n_comment'],$news['comm_count'])),
 
)
 
)
 
);
 
);
Line 1,038: Line 1,219:
  
 
Now we want to select the template we want to display.
 
Now we want to select the template we want to display.
<php>$roster->tpl->set_filenames(array('body' => 'news/news.html'));
+
<php>$roster->tpl->set_filenames(array('body' => $addon['basename'] . '/news.html'));
 
$roster->tpl->display('body');</php>
 
$roster->tpl->display('body');</php>
 
What happens here is we are assigning a 'handle' to a template file<br>
 
What happens here is we are assigning a 'handle' to a template file<br>
Line 1,045: Line 1,226:
 
You can assign multiple templates, then display them
 
You can assign multiple templates, then display them
 
<php>$roster->tpl->set_filenames(array(
 
<php>$roster->tpl->set_filenames(array(
'newshead' => 'news/news_head.html',
+
'newshead' => $addon['basename'] . '/news_head.html',
'body' => 'news/news.html',
+
'body' => $addon['basename'] . '/news.html',
'newsfooter' => 'news/news_head.html'
+
'newsfooter' => $addon['basename'] . '/news_head.html'
 
)
 
)
 
);
 
);
Line 1,063: Line 1,244:
 
This example is from the "News" AddOn
 
This example is from the "News" AddOn
  
roster/templates/default.news/news.html
+
roster/templates/default/news/news.html<br>
 +
or<br>
 +
roster/addons/news/templates/news.html
 
<pre><!-- INCLUDE news/news_head.html -->
 
<pre><!-- INCLUDE news/news_head.html -->
  
Line 1,106: Line 1,289:
 
** 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
 
** 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
 
* char_pre
** This mode is fired before any character is processed
+
** This mode is fired once per realm before any character is processed
 
* char
 
* char
 
** This mode fires for every character that is processed
 
** This mode fires for every character that is processed
 
* char_post
 
* char_post
** This mode is fired after every character is processed
+
** This mode is fired once per realm after every character is processed
 
* guild_pre
 
* guild_pre
 
** This mode is fired for each guild processed before any guild members are processed
 
** This mode is fired for each guild processed before any guild members are processed
 
* guild
 
* guild
** This mode is fired for each guild processed and for each guild member processed
+
** This mode is fired for each guild member processed
 
* guild_post
 
* guild_post
 
** This mode is fired for each guild processed after guild members are processed
 
** This mode is fired for each guild processed after guild members are processed
Line 1,129: Line 1,312:
 
*: Array, Addon data object, recieved in constructor.
 
*: Array, Addon data object, recieved in constructor.
 
*: This holds the addon's data from the database
 
*: 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>
 
* var <span style="color:maroon;">$files</span>
Line 1,172: Line 1,351:
 
You can add other methods or properties as you wish, but be warned that Roster may implement more update hook methods in future versions
 
You can add other methods or properties as you wish, but be warned that Roster may implement more update hook methods in future versions
  
 +
 +
 +
===Additional LUA Files During Update===
 +
The update class in Roster allows an addon to add more lua files for upload during the update process.
 +
 +
In your addon update hook class, add a member variable called $files.<br>
 +
This is an array of lua files you would like to add to the update process.
 +
 +
Specify the filename, without the .lua extension, in the update hook class constructor.
 +
{{Note|These file names must be lower case so they pass correctly through the parser.}}
 +
 +
<php> function addonnameUpdate( $data )
 +
{
 +
$this->data = $data;
 +
$this->files[] = 'luafilename';
 +
$this->files[] = 'anotherluafilename';
 +
}</php>
 +
The uploaded lua data is available in Update::uploadData
 +
<php>$update->uploadData['luafilename']
 +
$update->uploadData['anotherluafilename']</php>
  
  
Line 1,191: Line 1,390:
 
*/
 
*/
  
if ( !defined('ROSTER_INSTALLED') )
+
if ( !defined('IN_ROSTER') )
 
{
 
{
 
     exit('Detected invalid access to this file!');
 
     exit('Detected invalid access to this file!');
Line 1,292: Line 1,491:
 
}
 
}
 
}</php>
 
}</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===
+
==Variables and Functions for AddOns==
 
There are many variables, functions, and classes available for Addons to use
 
There are many variables, functions, and classes available for Addons to use
  
  
  
====Variables====
+
===Variables===
 
This is a list of variables that are available for your Addons
 
This is a list of variables that are available for your Addons
  
 
All variables are available whether during update hooks or in the framework
 
All variables are available whether during update hooks or in the framework
  
* <span style="color:maroon;">$roster</span>->db
+
* [[Roster:FunctionsOverview#.24roster-.3Edb|$roster->db]]
 
** Database layer for roster
 
** Database layer for roster
 
* <span style="color:maroon;">$roster</span>->locale->wordings
 
* <span style="color:maroon;">$roster</span>->locale->wordings
Line 1,371: Line 1,540:
 
* ROSTER_PATH
 
* ROSTER_PATH
 
** URL path to roster's root directory
 
** URL path to roster's root directory
* ROSTER_INSTALLED
+
* IN_ROSTER
** Constant saying that Roster is installed
+
** Constant saying that you are in the Roster framework
*: (addon.php already detects for this and dies if not found)
+
 
* ROSTER_MAXCHARLEVEL
 
* ROSTER_MAXCHARLEVEL
 
*: Maximum level that a character in WoW can achieve
 
*: Maximum level that a character in WoW can achieve
Line 1,403: Line 1,571:
 
** Addon's display icon
 
** Addon's display icon
 
* <span style="color:maroon;">$addon</span>['dir']
 
* <span style="color:maroon;">$addon</span>['dir']
** Full path to the Addon's folder
+
** File path to the Addon's folder
 
* <span style="color:maroon;">$addon</span>['url']
 
* <span style="color:maroon;">$addon</span>['url']
 
** URL path from the Roster base folder to the Addon's folder, this is not the full url path
 
** URL path from the Roster base folder to the Addon's folder, this is not the full url path
Line 1,410: Line 1,578:
 
* <span style="color:maroon;">$addon</span>['url_path']
 
* <span style="color:maroon;">$addon</span>['url_path']
 
** URL path to the Addon's folder, this is not the full url path
 
** URL path to the Addon's folder, this is not the full url path
* <span style="color:maroon;">$addon</span>['image_full']
+
* <span style="color:maroon;">$addon</span>['image_url']
 
** URL to the Addon's images/ folder, this is a full qualified url
 
** URL to the Addon's images/ folder, this is a full qualified url
 
* <span style="color:maroon;">$addon</span>['image_path']
 
* <span style="color:maroon;">$addon</span>['image_path']
 
** URL path to the Addon's images/ folder, this is not the full url path
 
** URL path to the Addon's images/ folder, this is not the full url path
 
* <span style="color:maroon;">$addon</span>['css_file']
 
* <span style="color:maroon;">$addon</span>['css_file']
** Full path to the Addon's style.css file
+
** File path to the Addon's [[#CSS_Styles|style.css]] file, empty string if not exist
 
* <span style="color:maroon;">$addon</span>['css_url']
 
* <span style="color:maroon;">$addon</span>['css_url']
** URL path to the Addon's css file, this is not the full url path
+
** URL path to the Addon's css file, this is not the full url path, empty string if not exist
 +
* <span style="color:maroon;">$addon</span>['tpl_dir']
 +
** File path to the Addon's template directory, empty string if not exist
 +
* <span style="color:maroon;">$addon</span>['tpl_url']
 +
** URL to the Addon's template directory, this is a full qualified url, empty string if not exist
 +
* <span style="color:maroon;">$addon</span>['tpl_url_path']
 +
** URL path to the Addon's template directory, this is not the full url path, empty string if not exist
 +
* <span style="color:maroon;">$addon</span>['tpl_image_url']
 +
** URL to the Addon's template/images directory, this is a full qualified url
 +
* <span style="color:maroon;">$addon</span>['tpl_image_path']
 +
** URL path to the Addon's template/images directory, this is not the full url path
 +
* <span style="color:maroon;">$addon</span>['tpl_css_file']
 +
** File path to the Addon's template based [[#CSS_Styles|style.css]] file, empty string if not exist
 +
* <span style="color:maroon;">$addon</span>['tpl_css_url']
 +
** URL path to the Addon's template based css file, this is not the full url path, empty string if not exist
 +
* <span style="color:maroon;">$addon</span>['inc_dir']
 +
** Full path to the Addon's inc/ folder
 
* <span style="color:maroon;">$addon</span>['conf_file']
 
* <span style="color:maroon;">$addon</span>['conf_file']
 
** Full path to the Addon's inc/conf.php file
 
** Full path to the Addon's inc/conf.php file
 +
* <span style="color:maroon;">$addon</span>['search_file']
 +
** Full path to the Addon's inc/search.inc.php file
 +
* <span style="color:maroon;">$addon</span>['search_class']
 +
** Addon's search class name
 
* <span style="color:maroon;">$addon</span>['locale_dir']
 
* <span style="color:maroon;">$addon</span>['locale_dir']
 
** Full path to the Addon's locale directory
 
** Full path to the Addon's locale directory
Line 1,425: Line 1,613:
 
** Full path to the Addon's admin directory
 
** Full path to the Addon's admin directory
 
* <span style="color:maroon;">$addon</span>['trigger_file']
 
* <span style="color:maroon;">$addon</span>['trigger_file']
** Full path to the Addon's inc/update_hook.php file
+
** Full path to the Addon's [[#AddOn_Update_Hook|inc/update_hook.php]] file
 
* <span style="color:maroon;">$addon</span>['ajax_file']
 
* <span style="color:maroon;">$addon</span>['ajax_file']
 
** Full path to the Addon's ajax.php
 
** Full path to the Addon's ajax.php
Line 1,433: Line 1,621:
  
  
====Functions====
+
===Variable Calls===
This is a list of functions that are available for your Addons
+
These are added to index.php for some additional support
  
<php>/**
+
If you add these to your addon, you can turn off the header, footer and menu on the page, these are always enabled by default.
* Starts or ends fancy bodering containers
+
<php>$roster->output['show_header'] = false; // Disable the roster header
*
+
$roster->output['show_menu'] = false;    // Disable roster menu
* @param string $style What bordering style to use
+
$roster->output['show_footer'] = false;  // Disable roster footer</php>
  * @param string $mode ( start | end )
+
* @param string $header_text Place text in a styled header
+
* @param string $hwidth Set a fixed width for the box
+
* @return string
+
*/
+
function border( $style , $mode , $header_text=null , $width='' )</php>
+
  
<php>/**
+
$roster->output['show_menu'] accepts a string or an array of button panel names to display<br>
* Highlight certain keywords in a SQL query
+
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
* @param string $sql Query string
+
<php>$roster->output['show_menu'] = array('util' => 1);  // Display only the util button panel, default opened
* @return string Highlighted string
+
$roster->output['show_menu'] = array('util' => 1,'char' => 0);  // Display only the util and char button panels: util default opened, char default closed
*/
+
$roster->output['show_menu']['custom'] = 1;  // Display the default panels and the custom button panel, default opened</php>
function sql_highlight( $sql )</php>
+
  
<php>/**
+
<php>$roster->output['html_head'] = 'string';</php>
* Clean replacement for die(), outputs a message with debugging info if needed and ends output
+
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
* @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>/**
+
<php>$roster->output['body_attr'] = 'string';</php>
* Draw a message box with the specified border color, then die cleanly
+
Accepts any string needing to be in the <body> tag in roster_header.tpl
*
+
* @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>/**
+
<php>$roster->output['body_onload'] = 'string';</php>
* This will remove HTML tags, javascript sections and white space
+
Accepts any string needing to be in <body onload=""> in roster_header.tpl
* 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>/**
+
Any output needed, just print or echo it<br>
* Recursively escape $array
+
Roster uses php's output buffering to capture all print or echo commands<br>
*
+
Then it echos the output where needed
* @param array $array The array to escape
+
* @return array The same array, escaped
+
*/
+
function escape_array( $array )</php>
+
  
<php>/**
 
* Recursively escape $array
 
*
 
* @param array $array
 
* The array to escape
 
* @return array
 
* The same array, escaped
 
*/
 
function stripslash_array( $array )</php>
 
  
<php>/**
 
* Converts a datetime field into a readable date
 
*
 
* @param string $datetime datetime field data in DB
 
* @param string $offset Offset in hours to calcuate time returned
 
* @return string formatted date string
 
*/
 
function readbleDate( $datetime , $offset=null )</php>
 
  
<php>/**
+
===Functions===
* Gets a file's extention passed as a string
+
This is a list of functions that are available for your Addons
*
+
* @param string $filename
+
* @return string
+
*/
+
function get_file_ext( $filename )</php>
+
  
<php>/**
+
View [[Roster:FunctionsOverview]] for details on available Roster functions
* 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>
+
 
+
<php>/**
+
* Debugging function dumps arrays/object formatted
+
* Do Not call this, call aprint()
+
*
+
* @param array $arr
+
* @param int $tab
+
* @return string
+
*/
+
function aprint( $arr , $prefix='' )</php>
+
 
+
<php>/**
+
* Helper function that returns the localized gem color in english
+
*
+
* @param string $socket_color
+
* @return string $color
+
*/
+
function socketColorEn( $socket_color, $locale )</php>
+
  
  
  
====Roster Authorization====
+
===Roster Authorization===
Like those nifty log-in boxes in Roster CP?<br>
+
Like those nifty log-in boxes in RosterCP?<br>
 
Now you can easily add one to your addon!
 
Now you can easily add one to your addon!
  
 
This checks if the user has admin access
 
This checks if the user has admin access
 
<php>// ----[ Check log-in ]-------------------------------------
 
<php>// ----[ Check log-in ]-------------------------------------
$roster_login = new RosterLogin();
 
 
 
// Disallow viewing of the page
 
// Disallow viewing of the page
if( $roster_login->getAuthorized() < 3 )
+
if( !$roster->auth->getAuthorized($required_level) )
 
{
 
{
include_once (ROSTER_BASE . 'roster_header.tpl');
 
$roster_menu = new RosterMenu;
 
print $roster_menu->makeMenu('main');
 
 
 
print
 
print
 
'<span class="title_text">Some Title</span><br />'.
 
'<span class="title_text">Some Title</span><br />'.
$roster_login->getMessage().
+
$roster->auth->getLoginForm();
$roster_login->getLoginForm();
+
  
include_once (ROSTER_BASE . 'roster_footer.tpl');
+
return; //Kicks out of the AddOn and back to the Roster framework
exit();
+
}
+
else
+
{
+
// continue with addon processing
+
 
}
 
}
 
// ----[ End Check log-in ]---------------------------------</php>
 
// ----[ End Check log-in ]---------------------------------</php>
* <span style="color:maroon;">$roster_login</span> - Roster Login class
+
* <span style="color:maroon;">$roster</span>->auth - Roster Auth class
* <span style="color:maroon;">$roster_login</span>->getAuthorized() - (int) Returns the id of access
+
* <span style="color:maroon;">$roster</span>->auth->getAuthorized() - (bool) Returns access granted or denied
** 1 - Guild Memeber Access
+
* <span style="color:maroon;">$roster</span>->auth->getMessage() - (string) Message sent from Roster Login, such as "Logged Out" or "Wrong Password"
** 2 - Officer Access
+
* <span style="color:maroon;">$roster</span>->auth->getLoginForm() - (string) The Roster Log-in form
** 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"
+
Also note that there is a log in box in the menu.
* <span style="color:maroon;">$roster_login</span>->getLoginForm() - (string) The Roster Log-in form
+
  
  
  
====Addon Credits====
+
===Addon Credits===
 
Link = http://[www.someurl.net]/roster/?p=credits (SEO: http://[www.someurl.net]/roster/credits.html)<br>
 
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
+
To get credits on the main credit page, set the $credits array in the AddOn's [[#Creating_the_Installer|inc/install.def.php]] file
 
<php>var $credits = array(
 
<php>var $credits = array(
 
array( "name"=> "Author Name",
 
array( "name"=> "Author Name",
Line 1,618: Line 1,693:
 
);</php>
 
);</php>
 
Replace the following
 
Replace the following
*"Addon Name" with your addon's name
+
* "Addon Name" with your addon's name
*"Author Name" with your (The addon's author) name
+
* "Author Name" with your (The addon's author) name
*"Extra Info" with a short description or additional info
+
* "Extra Info" with a short description or additional info
 
(Use <nowiki><br></nowiki> for line breaks)
 
(Use <nowiki><br></nowiki> for line breaks)
  
Line 1,628: Line 1,703:
  
  
====Tooltips====
+
===Tooltips===
 
<php>/**
 
<php>/**
 
  * Makes a tootip and places it into the tooltip array
 
  * Makes a tootip and places it into the tooltip array
Line 1,661: Line 1,736:
  
  
====Message Boxes====
+
===Message Boxes===
 
Functions to draw message boxes
 
Functions to draw message boxes
 
<php>/**
 
<php>/**

Latest revision as of 17:30, 5 June 2012

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 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: wowroster com (no longer online)
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


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)

Warning.png Important: DO NOT use php short tags in your php files as stated in the WoWRoster Coding Standards
Use the normal "long tag" as short tags can break page rendering with php "short_tags" set to "Off"

NO! <?
YES <?php
NO! <?=$var; ?>
YES <?php echo $var; ?>


Changes Since 1.7.3


AddOn Framework

Features

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


What it does

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

Best of all, this is transparent to you!


AddOn Directory Structure

Here is an example of an AddOn's directory structure

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


admin Folder

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

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

Info.png Note: The 'file' parameter is optional

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

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

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


char Folder (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

Info.png Note: 'rc' is the Region Code for US or EU realms

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


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

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


inc Folder

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

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

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


The util Scope

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

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


Other Files


Required Files

There are a few files that you must have


Linking to AddOns

You can link to any file in the root AddOn folder

The url to access each page is simple

Info.png Note: "file" is optional

The values explained


Creating the Installer

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

You should create a file called inc/install.def.php with in it a class that is named identical to your AddOn's install directory name, plus Install.

Info.png 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

Info.png 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

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


AddOn Install Class Methods


Queries

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


RosterCP API Entries

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


Creating/Editing Menu Entries

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


Other Installer Methods


Example File

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

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

<?php
/**
 * WoWRoster.net WoWRoster
 *
 * LICENSE: Licensed under the Creative Commons
 *          "Attribution-NonCommercial-ShareAlike 2.5" license
 *
 * @copyright  2002-2007 WoWRoster.net
 * @license    http://creativecommons.org/licenses/by-nc-sa/2.5   Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
 * @version    SVN: $Id: install.def.php 897 2007-05-06 00:35:11Z Zanix $
 * @link       http://www.wowroster.net
 * @package    SomeAddon
 * @subpackage Installer
*/
 
if ( !defined('IN_ROSTER') )
{
    exit('Detected invalid access to this file!');
}
 
/**
 * Installer SomeAddon
 *
 * @package    InstanceKeys
 * @subpackage Installer
 */
class 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


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


Info.png Note: The following variables are only displayed when $item['html'] is not set


Search Framework Variables


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:

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


Menu Bar Items

Usage

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

Options Blocks


Options


AddOn Config Function File

addons/addonname/admin/config.func.php


Locale Files

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

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

The folder structure for locale files is as follows:

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

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

Example:


Using Locale Strings

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

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

or

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

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

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

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

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


Example File

Example from the MembersList Roster AddOn
addons/memberslist/locale/deDE.php

Info.png 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->locale->act['add_news'],
 
	'U_ADD_NEWS'  => makelink('util-news-add'),
	'S_ADD_NEWS' => true,
	)
);

or

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

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


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

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

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

This is very useful for tables with repeating rows.

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

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

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

You can assign multiple templates, then display them

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

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

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

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


The Template Side

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

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

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

<!-- BEGIN news_row -->

{news_row.U_BORDER_S}

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

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

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

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

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

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

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

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

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


AddOn Update Hook

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

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


Properties

The following variables are required in the update hook class


Methods

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

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

These function fairly simmilar

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


Additional LUA Files During Update

The update class in Roster allows an addon to add more lua files for upload during the update process.

In your addon update hook class, add a member variable called $files.
This is an array of lua files you would like to add to the update process.

Specify the filename, without the .lua extension, in the update hook class constructor.

Info.png Note: These file names must be lower case so they pass correctly through the parser.

	function addonnameUpdate( $data )
	{
		$this->data = $data;
		$this->files[] = 'luafilename';
		$this->files[] = 'anotherluafilename';
	}

The uploaded lua data is available in Update::uploadData

$update->uploadData['luafilename']
$update->uploadData['anotherluafilename']


Example Update Hook File

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

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


Variables and Functions for AddOns

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


Variables

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

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


Variable Calls

These are added to index.php for some additional support

If you add these to your addon, you can turn off the header, footer and menu on the page, these are always enabled by default.

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

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

$roster->output['show_menu'] = array('util' => 1);  // Display only the util button panel, default opened
$roster->output['show_menu'] = array('util' => 1,'char' => 0);  // Display only the util and char button panels: util default opened, char default closed
$roster->output['show_menu']['custom'] = 1;  // Display the default panels and the custom button panel, default opened 

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

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

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

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

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

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


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


Functions

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

View Roster:FunctionsOverview for details on available Roster functions


Roster Authorization

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

This checks if the user has admin access

// ----[ Check log-in ]-------------------------------------
// Disallow viewing of the page
if( !$roster->auth->getAuthorized($required_level) )
{
	print
	'<span class="title_text">Some Title</span><br />'.
	$roster->auth->getLoginForm();
 
	return; //Kicks out of the AddOn and back to the Roster framework
}
// ----[ End Check log-in ]--------------------------------- 

Also note that there is a log in box in the menu.


Addon Credits

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

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

Replace the following

(Use <br> for line breaks)

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


Tooltips

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

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

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

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

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

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


Message Boxes

Functions to draw message boxes

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

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

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

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