Roster:Addon:AddonSDK

From WoWRosterWiKi
(Difference between revisions)
Jump to: navigation, search
Line 23: Line 23:
 
==Certified WoWRoster AddOn==
 
==Certified WoWRoster AddOn==
 
[[Image:Certaddon.png|frame|Certified WoWRoster AddOn]]
 
[[Image:Certaddon.png|frame|Certified WoWRoster AddOn]]
−
AddOns that conform to our [[CodingStandards|Coding Standards]] and the basic outline described within this document, will be given a "<span style="color: darkred;">AddOn Framework Standards Compliant</span>" stamp of approval.
+
AddOns that conform to our [[CodingStandards|Coding Standards]] and the basic outline described within this document, will be given a "<span style="color:maroon;">AddOn Framework Standards Compliant</span>" stamp of approval.
 +
 
  
  
Line 41: Line 42:
 
*: (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 - <span style="color:maroon;">$roster->db</span>
 
* 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
+
* Roster main database tables are not edited, unless you provide a clean way to revert the data in your uninstall
−
 
+
  
  
Line 68: Line 68:
 
<span style="color:red;">NO!</span> <code><?    ?></code><br>
 
<span style="color:red;">NO!</span> <code><?    ?></code><br>
 
<span style="color:green;">YES</span> <code><?php  ?></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"
 
Use the "long tags" as the short ones can break web servers with short_tags set to "off"
 
|}
 
|}
Line 74: Line 76:
  
  
 +
==Changes Since 1.7.3==
 +
* All AddOns need to be installed using an install definition file install.def.php.
 +
* During install, database tables, graphical configuration, menu buttons, and update hooks can be registered with the main framework.
 +
* menu.php file is no longer required.
 +
* conf.php is still used because there may be more to initialize than just settings.
 +
* Several variables in addon.php, most notably $addonDir, have changed names.
 +
* localization.php is no longer used.
 +
** Locale files are now placed in the locale subfolder of the addon and are named for the locale they are made for
 +
* Configuration from database is automatically added. Addons are initialized in this order:
 +
** Addon registration record
 +
** Other constants (locations of addon files and the addon base dir)
 +
** Database configuration, if it exists
 +
** Localization files
 +
*** The addon framework uses the $roster->mulitlanguages array to automatically add the default Roster locales
 +
** conf.php file
 +
* The addon is called differently now.
 +
** Details are below.
 +
* You do not know the basename at design time.
 +
** Please use the $addon['basename'] variable for this at all times.
 +
* On lua updates, the addon's update_hook.php is included once.
 +
** Details for the new update hook structure is below
 +
* Menu buttons are created in the database using installer functions
 +
* New libraries available:
 +
** lib/install.lib.php: AddOn install/upgrade/uninstall class
 +
** lib/config.lib.php: AddOn config class
 +
** lib/roster.php: Roster global class
 +
*** This holds all of roster's config, locale strings, error control, some output variables, and the db layer
 +
** lib/minixml.lib.php: A XML file reader and creator
  
  
Line 81: Line 111:
 
# Uses output buffering, which means all the output is stored in a variable that is sent to the browser
 
# Uses output buffering, which means all the output is stored in a variable that is sent to the browser
 
# Do not have to include Roster's conf.php
 
# Do not have to include Roster's conf.php
−
# Do not have to include/declare $roster object
+
# Do not have to include/declare <span style="color:maroon;">$roster</span> object
 
# Do not have to connect to Roster's database
 
# Do not have to connect to Roster's database
 
# Do not have to include your conf.php
 
# Do not have to include your conf.php
 
# AddOn files: conf.php, style.css, and locale files are OPTIONAL!
 
# AddOn files: conf.php, style.css, 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
 +
  
  
 
===What it does===
 
===What it does===
−
# Includes all Roster config variables for you to use ($roster->config)
+
# Includes all Roster config variables for you to use (<span style="color:maroon;">$roster</span>->config)
−
# Includes all Roster SQL functions for your use ($roster->db)
+
# Includes all Roster SQL functions for your use (<span style="color:maroon;">$roster</span>->db)
−
# Includes all Roster language variables for you ($roster->locale->wordings, $roster->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
 
# The Roster header, footer, and menu are included to your files.
 
# The Roster header, footer, and menu are included to your files.
Line 97: Line 128:
  
 
Best of all, this is transparent to you!
 
Best of all, this is transparent to you!
 +
  
  
Line 140: Line 172:
 
       |_ util.php
 
       |_ util.php
 
</pre>
 
</pre>
 +
 +
  
 
====admin Folder====
 
====admin Folder====
−
The admin folder is to house files for the Roster CP
+
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
 
Normally you'll never need files here because the Config API can handle most configuration needs
  
Line 163: Line 197:
 
*: Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-info-display
 
*: Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-info-display
 
*: SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/info/display.html
 
*: SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/info/display.html
 +
  
  
Line 219: Line 254:
 
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guildless-addonname-file&realm=name
 
* Normal Link - http://[www.someurl.net]/roster/trunk/?p=guildless-addonname-file&realm=name
 
* SEO Link - http://[www.someurl.net]/roster/trunk/guildless/addonname/file/realm=name.html
 
* SEO Link - http://[www.someurl.net]/roster/trunk/guildless/addonname/file/realm=name.html
 +
  
  
Line 227: Line 263:
  
 
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 232: Line 269:
 
Where locale translation files go<br>
 
Where locale translation files go<br>
 
See below for more info [[#Locale Files|Locale Files]]
 
See below for more info [[#Locale Files|Locale Files]]
 +
  
  
Line 249: Line 287:
 
* 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&realm=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/realm=name.html
 +
  
  
Line 268: Line 307:
 
* conf.php - This is included before any other addon file, any initialization can be done here
 
* conf.php - This is included before any other addon file, any initialization can be done here
 
* index.php - The main file for the util scope
 
* index.php - The main file for the util scope
−
* [[#Creating_the_Installer|install.def.php]] - The main file for the util scope
+
* [[#Creating_the_Installer|install.def.php]] - The AddOn's install/upgrade/uninstall definition file
−
* style.css - A custom css style for the AddOn
+
* [[#CSS_Styles|style.css]] - A custom css style for the AddOn
 +
* [[#AddOn_Update_Hook|update_hook.php]] - Update Hook file
 +
 
  
  
Line 275: Line 316:
 
There are a few files that you must have
 
There are a few files that you must have
 
* [[#Creating_the_Installer|addons/addoname/install.def.php]] (AddOn install/upgrade/uninstall file)
 
* [[#Creating_the_Installer|addons/addoname/install.def.php]] (AddOn install/upgrade/uninstall file)
 +
  
  
Line 294: Line 336:
 
* addonname - The name of the AddOn you are accessing
 
* addonname - The name of the AddOn you are accessing
 
* file - The file you are accessing
 
* file - The file you are accessing
−
 
  
  
Line 301: Line 342:
 
This installer requires a similar install file definition as DragonFly CMS, with
 
This installer requires a similar install file definition as DragonFly CMS, with
 
some important exceptions:
 
some important exceptions:
−
* SQL entries are the same as as passing it to mysql_query() using $installer->add_query($sqlstring)
+
* SQL entries are the same as as passing it to mysql_query() using <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>)
−
* No rollback data per query. Instead, call $installer->add_backup($table_name) for each table you want restored in case of an upgrade/uninstall failure.
+
* No rollback data per query. Instead, call <span style="color:maroon;">$installer</span>->add_backup(<span style="color:maroon;">$table_name</span>) for each table you want restored in case of an upgrade/uninstall failure.
 
*: Any backup tables you create are automatically deleted in rollback.
 
*: Any backup tables you create are automatically deleted in rollback.
 
* Different required variables to be set.
 
* Different required variables to be set.
Line 308: Line 349:
 
You should create a file called install.def.php with in it a class that is named identical to your AddOn's install directory name.<br>
 
You should create a file called install.def.php with in it a class that is named identical to your AddOn's install directory name.<br>
 
This name will be referred to as your AddOn's basename.
 
This name will be referred to as your AddOn's basename.
 +
 +
  
 
===Properties===
 
===Properties===
−
* var $active
+
* var <span style="color:maroon;">$active</span>
 
*: Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.
 
*: Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.
  
−
* var $version
+
* var <span style="color:maroon;">$version</span>
 
*: 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 that includes a database update, or any update if you wish.
  
−
* var $icon
+
* 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
  
−
* var $fullname
+
* 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.
  
−
* var $description
+
* var <span style="color:maroon;">$description</span>
 
*: String, a sort description of your AddOn.
 
*: String, a sort description of your AddOn.
  
−
* var $credits
+
* var <span style="color:maroon;">$credits</span>
 
*: Credits information.
 
*: Credits information.
−
<pre>array(
+
<php>$credits = array(
 
array( "name"=> "Name",
 
array( "name"=> "Name",
 
"info"=> "Some Info"),
 
"info"=> "Some Info"),
 
array( "name"=> "Another Name",
 
array( "name"=> "Another Name",
 
"info"=> "More Info"),
 
"info"=> "More Info"),
−
);</pre>
+
);</php>
 +
 
  
  
−
===Functions===
+
===Methods===
 
* install()
 
* install()
 
*: Here you can add all queries for a fresh install.
 
*: Here you can add all queries for a fresh install.
Line 344: Line 388:
 
*: Return true on success, false on failure.
 
*: Return true on success, false on failure.
  
−
* upgrade($oldversion)
+
* upgrade(<span style="color:maroon;">$oldversion</span>)
 
*: Here you can add all queries for an upgrade.
 
*: Here you can add all queries for an upgrade.
−
*:: <span style="color:darkred;">$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.}}
 
{{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.}}
Line 354: Line 398:
 
*: No parameters.
 
*: No parameters.
 
*: Return true on success, false on failure
 
*: Return true on success, false on failure
 +
  
  
 
===Adding Queries===
 
===Adding Queries===
−
Queries are added to the install using the $installer functions.
+
Queries are added to the install using the <span style="color:maroon;">$installer</span> methods.
  
−
* $installer->add_query($sqlstring);
+
* <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>);
 
*: Any valid SQL query
 
*: Any valid SQL query
  
−
* $installer->add_backup($table)
+
* <span style="color:maroon;">$installer</span>->add_backup(<span style="color:maroon;">$table</span>)
 
*: Makes a temporary copy of a table and its contents that is put back in case of a rollback
 
*: Makes a temporary copy of a table and its contents that is put back in case of a rollback
  
−
* $installer->add_drop($table)
+
* <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
  
−
* $installer->add_config($sqlstring);
+
* <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
 
*: These entries will be used to build a config page through Roster's config page API
 +
  
  
Line 378: Line 424:
 
Note the title should be unique per AddOn.
 
Note the title should be unique per AddOn.
  
−
* $installer->add_menu_button($title, $scope, $url, %icon)
+
* <span style="color:maroon;">$installer</span>->add_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
 
*: Adds a menu button. Parameters:
 
*: Adds a menu button. Parameters:
−
*: $title
+
*: <span style="color:maroon;">$title</span>
 
*:: The localization key for the menu button's title.
 
*:: The localization key for the menu button's title.
−
*: $scope
+
*: <span style="color:maroon;">$scope</span>
 
*:: The scope of the link ('util','realm','guild','guildless','char')
 
*:: The scope of the link ('util','realm','guild','guildless','char')
−
*: $url
+
*: <span style="color:maroon;">$url</span>
 
*:: The url parameters this button should call the AddOn with
 
*:: The url parameters this button should call the AddOn with
−
*: $icon
+
*: <span style="color:maroon;">$icon</span>
 
*:: An icon to display in the button
 
*:: An icon to display in the button
  
−
* $installer->update_menu_button($title, $scope, $url, $icon)
+
* <span style="color:maroon;">$installer</span>->update_menu_button($title, $scope, $url, $icon)
 
*: Changes menu button. Parameters:
 
*: Changes menu button. Parameters:
−
*: $title
+
*: <span style="color:maroon;">$title</span>
 
*:: The localization key for the menu button's title.
 
*:: The localization key for the menu button's title.
−
*: $scope
+
*: <span style="color:maroon;">$scope</span>
 
*:: The scope of the link ('util','realm','guild','guildless','char')
 
*:: The scope of the link ('util','realm','guild','guildless','char')
−
*: $url
+
*: <span style="color:maroon;">$url</span>
 
*:: The url parameters this button should call the AddOn with
 
*:: The url parameters this button should call the AddOn with
−
*: $icon
+
*: <span style="color:maroon;">$icon</span>
 
*:: An icon to display in the button
 
*:: An icon to display in the button
  
−
* $installer->remove_menu_button($title)
+
* <span style="color:maroon;">$installer</span>->remove_menu_button($title)
 
*: Removes a menu button. Parameters:
 
*: Removes a menu button. Parameters:
−
*: $title
+
*: <span style="color:maroon;">$title</span>
 
*:: The localization key for the menu button's title.
 
*:: The localization key for the menu button's title.
 +
  
  
Line 502: Line 549:
 
}
 
}
 
}</php>
 
}</php>
−
 
  
  
Line 513: Line 559:
 
Items of the page, pageframe, and pagehide class contain option blocks.<br>
 
Items of the page, pageframe, and pagehide class contain option blocks.<br>
 
Items of the blockframe or blockhide class contain options.
 
Items of the blockframe or blockhide class contain options.
 +
  
  
Line 518: Line 565:
 
* 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
−
*: $installer->add_config("'110','config_name',NULL,'blockframe','menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'110','config_name',NULL,'blockframe','menu'")
−
*: $installer->add_config("'150', 'config_name', NULL, 'page{1', 'menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'150', 'config_name', NULL, 'page{1', 'menu'")
  
 
* link
 
* link
 
*: An external link to be opened in the same window
 
*: An external link to be opened in the same window
−
*: $installer->add_config("120,'config_name','link_value','link','menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("120,'config_name','link_value','link','menu'")
  
 
* newlink
 
* newlink
 
*: An external link to be opened in a new window
 
*: An external link to be opened in a new window
−
*: $installer->add_config("170,'config_name','<nowiki>http://www.someurl.com</nowiki>','newlink','menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("170,'config_name','<nowiki>http://www.someurl.com</nowiki>','newlink','menu'")
  
 
* makelink
 
* makelink
 
*: Passes this through Roster's makelink() function to generate a correct link to another page in Roster.
 
*: Passes this through Roster's makelink() function to generate a correct link to another page in Roster.
−
*: $installer->add_config("120,'config_name','link_value','makelink','menu'")
+
*: <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 makelink, except it opens a new browser window.
−
*: $installer->add_config("180,'config_name','link_value','makenewlink','menu'")
+
*: <span style="color:maroon;">$installer</span>->add_config("180,'config_name','link_value','makenewlink','menu'")
 +
 
  
  
Line 541: Line 589:
 
* page{n
 
* page{n
 
*: n columns of options blocks
 
*: n columns of options blocks
−
*: $installer->add_config("'4001', 'menu_conf_wide', NULL, 'page{2', 'menu_conf'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4001', 'menu_conf_wide', NULL, 'page{2', 'menu_conf'")
  
 
* pageframe{n
 
* pageframe{n
 
*: n columns of options blocks in a border
 
*: n columns of options blocks in a border
−
*: $installer->add_config("'4025', 'menu_conf_left', NULL, 'pageframe{3', 'menu_conf'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4025', 'menu_conf_left', NULL, 'pageframe{3', 'menu_conf'")
  
 
* pagehide{n
 
* pagehide{n
 
*: n columns of options blocks in a border, with a show/hide option
 
*: n columns of options blocks in a border, with a show/hide option
−
*: $installer->add_config("'4020', 'menu_conf_hidden', NULL, 'pagehide{1', 'menu_conf'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4020', 'menu_conf_hidden', NULL, 'pagehide{1', 'menu_conf'")
  
 
* blockframe
 
* blockframe
 
*: A list of options in a border
 
*: A list of options in a border
−
*: $installer->add_config("'4000, 'menu_conf_top', NULL, 'blockframe', 'menu_conf'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4000, 'menu_conf_top', NULL, 'blockframe', 'menu_conf'")
  
 
* blockhide
 
* blockhide
 
*: A list of options in a border, with a show/hide option
 
*: A list of options in a border, with a show/hide option
−
*: $installer->add_config("'4050, 'menu_conf_bottom', NULL, 'blockhide', 'menu_conf'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4050, 'menu_conf_bottom', NULL, 'blockhide', 'menu_conf'")
  
 
* function{name
 
* function{name
 
*: Calls the function called name with no parameters to produce the HTML for the page.
 
*: Calls the function called name with no parameters to produce the HTML for the page.
 
*: If this is a tab (directly linked from the switch menu on the left side) it is put outside the main form so you can put forms in it.
 
*: If this is a tab (directly linked from the switch menu on the left side) it is put outside the main form so you can put forms in it.
−
*: $installer->add_config("'4470', 'menu_conf_right', NULL, 'function{newForm', 'menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4470', 'menu_conf_right', NULL, 'function{newForm', 'menu_conf_top'")
 +
 
  
  
Line 568: Line 617:
 
* text{n|m
 
* text{n|m
 
*: A text box m characters wide, maximum of n characters input
 
*: A text box m characters wide, maximum of n characters input
−
*: $installer->add_config("'1110','page_size','0','text{4|30','menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'1110','page_size','0','text{4|30','menu_conf_top'")
  
 
* radio{op1^val1|op2^val2|op3^val3...
 
* radio{op1^val1|op2^val2|op3^val3...
Line 574: Line 623:
 
*: Which produce values val1, val2, val3,...
 
*: Which produce values val1, val2, val3,...
 
*: Labels are literal, not localization keys.
 
*: Labels are literal, not localization keys.
−
*: $installer->add_config("'1010','nojs','0','radio{Server^1|Client^0','menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'1010','nojs','0','radio{Server^1|Client^0','menu_conf_top'")
  
 
* select{op1^val1|op2^val2|op3^val3...
 
* select{op1^val1|op2^val2|op3^val3...
Line 580: Line 629:
 
*: Which produce values val1, val2, val3,...
 
*: Which produce values val1, val2, val3,...
 
*: Labels are literal, not localization keys.
 
*: Labels are literal, not localization keys.
−
*: $installer->add_config("'1020','def_sort','Note','select{Public Note^Note|Officer Note^OfficerNote','menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'1020','def_sort','Note','select{Public Note^Note|Officer Note^OfficerNote','menu_conf_top'")
  
 
* function{name
 
* function{name
 
*: Calls the function called name with the option record as parameter to produce the HTML for the option.
 
*: Calls the function called name with the option record as parameter to produce the HTML for the option.
−
*: $installer->add_config("'4270', 'left_text', 'VERANDA.TTF', 'function{fontFiles', 'menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4270', 'left_text', 'VERANDA.TTF', 'function{fontFiles', 'menu_conf_top'")
  
 
* display
 
* display
 
*: Displays the option's setting.
 
*: Displays the option's setting.
−
*: $installer->add_config("'3, 'help_text', 'This is to help', 'display', 'menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'3, 'help_text', 'This is to help', 'display', 'menu_conf_top'")
  
 
* color
 
* color
 
*: Enables the use of the color picker javascript to pick a color from a pallet
 
*: Enables the use of the color picker javascript to pick a color from a pallet
−
*: $installer->add_config("'4230', 'menu_left_barcolor', '#3e0000', 'color', 'menu_conf_top'")
+
*: <span style="color:maroon;">$installer</span>->add_config("'4230', 'menu_left_barcolor', '#3e0000', 'color', 'menu_conf_top'")
 +
 
  
  
Line 599: Line 649:
 
*: Both function types call functions that can be defined in a file called 'config.func.php' in your AddOn's admin/ directory.
 
*: Both function types call functions that can be defined in a file called 'config.func.php' in your AddOn's admin/ directory.
 
*: If this file has a function named topBox(), the html returned by this function will be put above the options in the middle column.
 
*: If this file has a function named topBox(), the html returned by this function will be put above the options in the middle column.
−
 
  
  
Line 627: Line 676:
 
* This way, you only need to have enUS.php
 
* This way, you only need to have enUS.php
 
* Later, if other locales are translated, they can be placed into the locale folder and Roster will detect them based on the locales set in localization/languages.php
 
* Later, if other locales are translated, they can be placed into the locale folder and Roster will detect them based on the locales set in localization/languages.php
 +
  
  
Line 642: Line 692:
  
 
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
 
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 File===
Line 715: Line 767:
 
$lang['admin']['minPvPLogver'] = "Min PvPLog version|Minimum PvPLog Version zum Upload";
 
$lang['admin']['minPvPLogver'] = "Min PvPLog version|Minimum PvPLog Version zum Upload";
 
</php>
 
</php>
−
 
  
  
Line 751: Line 802:
  
 
I assume you know what css is...
 
I assume you know what css is...
−
 
  
  
Line 758: Line 808:
 
The update hook is a file that ties into the lua upload process<br>
 
The update hook is a file that ties into the lua upload process<br>
 
You can specify any additional lua files you may you need
 
You can specify any additional lua files you may you need
 +
 +
There are a few hook modes that an AddOn can make use of
 +
* update
 +
** This mode does not hook into the CharacterProfiler upload process and is a good way to parse and process data from lua files other than CharacterProfiler
 +
* char_pre
 +
** This mode is fired before any character is processed
 +
* char
 +
** This mode fires for every character that is processed
 +
* char_post
 +
** This mode is fired after every character is processed
 +
* guild_pre
 +
** This mode is fired for each guild processed before any guild members are processed
 +
* guild
 +
** This mode is fired for each guild processed and for each guild member processed
 +
* guild_post
 +
** This mode is fired for each guild processed after guild members are processed
 +
 +
  
 
===Properties===
 
===Properties===
 
The following variables are required in the update hook class
 
The following variables are required in the update hook class
  
−
* var $messages
+
* var <span style="color:maroon;">$messages</span>
 
*: String, any messages or output.
 
*: String, any messages or output.
  
−
* var $data
+
* var <span style="color:maroon;">$data</span>
 
*: 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 $icon
+
* 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
  
−
* var $files
+
* var <span style="color:maroon;">$files</span>
 
*: array, An array of additional lua files that your addon needs.
 
*: array, An array of additional lua files that your addon needs.
 
*: If you are using CharacterProfiler for data, there is no need to list it here.
 
*: If you are using CharacterProfiler for data, there is no need to list it here.
Line 779: Line 847:
  
  
 +
===Methods===
 +
* addonUpdate()
 +
*: The constructor for the update hook
 +
*: This is the only required method in an update hook class
 +
*: The addons data is passed to this function, you should set the passed data to an internal property variable
 +
<php> function addonUpdate($data)
 +
{
 +
$this->data = $data;
 +
}</php>
 +
 +
The following methods are reserved for update hooks<br>
 +
Descriptions for these methods are above and are not required
 +
 +
These function fairly simmilar
 +
* update()
 +
* char_pre(<span style="color:maroon;">$characters</span>)
 +
** <span style="color:maroon;">$characters</span> - Array: All characters and their data in CharacterProfiler.lua
 +
* char(<span style="color:maroon;">$char</span>, <span style="color:maroon;">$memberid</span>)
 +
** <span style="color:maroon;">$char</span> - Array: Character data array for the current processed character
 +
** <span style="color:maroon;">$memberid</span> - Int: Member id from members table
 +
* char_post(<span style="color:maroon;">$characters</span>)
 +
** <span style="color:maroon;">$characters</span> - Array: All characters and their data in CharacterProfiler.lua
 +
* guild_pre(<span style="color:maroon;">$guild</span>)
 +
** <span style="color:maroon;">$guild</span> - Array: All guilds and their data in CharacterProfiler.lua
 +
* guild(<span style="color:maroon;">$char</span>, <span style="color:maroon;">$memberid</span>)
 +
** <span style="color:maroon;">$char</span> - Array: Member data array for the current processed member
 +
** <span style="color:maroon;">$memberid</span> - Int: Member id from members table
 +
* guild_post(<span style="color:maroon;">$guild</span>)
 +
** <span style="color:maroon;">$guild</span> - Array: All guilds and their data in CharacterProfiler.lua
 +
 +
You can add other methods or properties as you wish, but be warned that Roster may implement more update hook methods in future versions
 +
 +
 +
 +
===Example Update Hook File===
 +
This is an example update hook file<br>
 +
Look at memberslist and pvplog (example of additional lua file upload and processing) for more complex examples
 
<php><?php
 
<php><?php
 
/**
 
/**
Line 894: Line 999:
 
}
 
}
 
}</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['roster_show_menu'] = 'main';  // Display the main button listing
 +
$roster->output['roster_show_menu'] = array('main','char');  // Display the main and char button listing</php>
 +
 +
<php>$roster->output['html_head'] = 'string';</php>
 +
Accepts any string needing to be in the html header for your addon, such as javascript inclusion<br>
 +
roster_header.tpl will pick this variable up and place its contents in the header
 +
 +
<php>$roster->output['body_attr'] = 'string';</php>
 +
Accepts any string needing to be in the <body> tag in roster_header.tpl
 +
 +
<php>$roster->output['body_onload'] = 'string';</php>
 +
Accepts any string needing to be in <body onload=""> in roster_header.tpl
 +
 +
 +
Any output needed, just print or echo it<br>
 +
Roster uses php's output buffering to capture all print or echo commands<br>
 +
Then it echos the output where needed
 +
 +
 +
 +
===Variables and Functions for AddOns===
 +
There are many variables, functions, and classes available for Addons to use
 +
 +
 +
 +
====Variables====
 +
This is a list of variables that are available for your Addons
 +
 +
All variables are available whether during update hooks or in the framework
 +
 +
* <span style="color:maroon;">$roster</span>->db
 +
** Database layer for roster
 +
* <span style="color:maroon;">$roster</span>->locale->wordings
 +
** Every locale array
 +
* <span style="color:maroon;">$roster</span>->locale->act
 +
** The current global locale string array
 +
* <span style="color:maroon;">$roster</span>->config
 +
** The roster configuration array
 +
* <span style="color:maroon;">$roster</span>->pages
 +
** Array of current pages accessed
 +
* <span style="color:maroon;">$roster</span>->data
 +
** Current scope data
 +
*: For a list of what is in here, see RosterDiag
 +
* DIR_SEP
 +
** OS specific directory separator
 +
* ROSTER_BASE
 +
** Full path to roster directory including DIR_SEP at the end
 +
* ROSTER_LIB
 +
** Full path to roster lib directory including DIR_SEP at the end
 +
* ROSTER_ADDONS
 +
** Full path to roster addons directory including DIR_SEP at the end
 +
* ROSTER_ADMIN
 +
** Full path to roster admin directory including DIR_SEP at the end
 +
* ROSTER_AJAX
 +
** Full path to rosters ajax directory including DIR_SEP at the end
 +
* ROSTER_LOCALE
 +
** Full path to roster localization directory including DIR_SEP at the end
 +
* ROSTER_VERSION
 +
** Current Version of Roster
 +
* ROSTER_URL
 +
** Full valid URL to roster's root directory
 +
* ROSTER_PATH
 +
** URL path to roster's root directory
 +
* ROSTER_INSTALLED
 +
** Constant saying that Roster is installed
 +
*: (addon.php already detects for this and dies if not found)
 +
* ROSTER_MAXCHARLEVEL
 +
*: Maximum level that a character in WoW can achieve
 +
* ROSTER_MAXSKILLLEVEL
 +
*: Maximum skill level that a character in WoW can achieve
 +
* <span style="color:maroon;">$roster</span>->db->prefix
 +
** Database table prefix
 +
* <span style="color:maroon;">$roster</span>->db->table(<span style="color:maroon;">$tablename</span>, <span style="color:maroon;">$addon</span>='')
 +
** Returns a table name including the database prefix
 +
*** This will return 'databaseprefix_tablename'
 +
** When $addon is passed, use the basename of the addon
 +
*** This will return 'databaseprefix_addon_basename_tablename'
 +
* <span style="color:maroon;">$addon</span>['addon_id']
 +
** Addon database id
 +
* <span style="color:maroon;">$addon</span>['basename']
 +
** Addon folder name
 +
* <span style="color:maroon;">$addon</span>['version']
 +
** Addon version
 +
* <span style="color:maroon;">$addon</span>['active']
 +
** 0 - if the Addon is disabled : 1 -  if the Addon is enabled
 +
** Use addon_active('basename') to check if an addon is enabled
 +
* <span style="color:maroon;">$addon</span>['fullname']
 +
** Addon's full name for display
 +
* <span style="color:maroon;">$addon</span>['description']
 +
** Short description of the addon
 +
* <span style="color:maroon;">$addon</span>['credits']
 +
** Serialized array of credits
 +
* <span style="color:maroon;">$addon</span>['icon']
 +
** Addon's display icon
 +
* <span style="color:maroon;">$addon</span>['dir']
 +
** Full path to the Addon's folder
 +
* <span style="color:maroon;">$addon</span>['css_file']
 +
** Full path to the Addon's style.css file
 +
* <span style="color:maroon;">$addon</span>['css_url']
 +
** URL path to the Addon's css file, this is not the full url path
 +
* <span style="color:maroon;">$addon</span>['conf_file']
 +
** Full path to the Addon's conf.php file
 +
* <span style="color:maroon;">$addon</span>['locale_dir']
 +
** Full path to the Addon's locale directory
 +
* <span style="color:maroon;">$addon</span>['admin_dir']
 +
** Full path to the Addon's admin directory
 +
* <span style="color:maroon;">$addon</span>['trigger_file']
 +
** Full path to the Addon's update_hook.php file
 +
* <span style="color:maroon;">$addon</span>['ajax_file']
 +
** Full path to the Addon's ajax.php
 +
* <span style="color:maroon;">$addon</span>['config']
 +
** Addon's configuration array
 +
 +
 +
 +
====Functions====
 +
This is a list of functions that are available for your Addons
 +
 +
<php>/**
 +
* Starts or ends fancy bodering containers
 +
*
 +
* @param string $style What bordering style to use
 +
* @param string $mode ( 'start' | 'end' )
 +
* @param string $header_text (optional) Place text in a styled header
 +
* @return string
 +
*/
 +
function border($style,$mode,$header_text=null)</php>
 +
 +
<php>/**
 +
* Highlight certain keywords in a SQL query
 +
*
 +
* @param string $sql Query string
 +
* @return string Highlighted string
 +
*/
 +
function sql_highlight( $sql )</php>
 +
 +
<php>/**
 +
* Clean replacement for die(), outputs a message with debugging info if needed and ends output
 +
*
 +
* @param string $text Text to display on error page
 +
* @param string $title Title to place on web page
 +
* @param string $file Filename to display
 +
* @param string $line Line in file to display
 +
* @param string $sql Any SQL text to display
 +
*/
 +
function die_quietly( $text='', $title='', $file='', $line='', $sql='' )</php>
 +
 +
<php>/**
 +
* Draw a message box with the specified border color, then die cleanly
 +
*
 +
* @param string $message | The message to display inside the box
 +
* @param string $title | The box title (default = 'Message')
 +
* @param string $style | The border style (default = sred)
 +
*/
 +
function roster_die( $message , $title = 'Message' , $style = 'sred' )</php>
 +
 +
<php>/**
 +
* This will remove HTML tags, javascript sections and white space
 +
* It will also convert some common HTML entities to their text equivalent
 +
*
 +
* @param string $file
 +
*/
 +
function stripAllHtml($string)</php>
 +
 +
<php>/**
 +
* This will check if the given Filename is an image
 +
*
 +
* @param imagefile $file
 +
* @return mixed The extentsion if the filetype is an image, false if it is not
 +
*/
 +
function check_if_image( $imagefilename )</php>
 +
 +
<php>/**
 +
* Recursively escape $array
 +
*
 +
* @param array $array The array to escape
 +
* @return array The same array, escaped
 +
*/
 +
function escape_array( $array )</php>
 +
 +
<php>/**
 +
* Converts a datetime field into a readable date
 +
*
 +
* @param string $datetime datetime field data in DB
 +
* @return string formatted date string
 +
*/
 +
function readbleDate( $datetime )</php>
 +
 +
<php>/**
 +
* Gets a file's extention passed as a string
 +
*
 +
* @param string $filename
 +
* @return string
 +
*/
 +
function get_file_ext( $filename )</php>
 +
 +
<php>/**
 +
* Converts seconds to a string delimited by time values
 +
* Will show d,h,m,s
 +
*
 +
* @param string $seconds
 +
* @return string
 +
*/
 +
function seconds_to_time( $seconds )</php>
 +
 +
<php>/**
 +
* Check to see if an addon is active or not
 +
*
 +
* @param string $name | Addon basename
 +
* @return bool
 +
*/
 +
function active_addon( $name )</php>
 +
 +
<php>/**
 +
* Handles retrieving the contents of a URL using multiple methods
 +
*
 +
* @param string $url | URL to retrieve
 +
* @param int $timeout | Timeout
 +
* @return mixed | False on error, contents on success
 +
*/
 +
function urlgrabber( $url , $timeout = 5 )</php>
 +
 +
 +
 +
====Roster Authorization====
 +
Like those nifty log-in boxes in Roster CP?<br>
 +
Now you can easily add one to your addon!
 +
 +
This checks if the user has admin access
 +
<php>// ----[ Check log-in ]-------------------------------------
 +
$roster_login = new RosterLogin();
 +
 +
// Disallow viewing of the page
 +
if( $roster_login->getAuthorized() < 3 )
 +
{
 +
include_once (ROSTER_BASE . 'roster_header.tpl');
 +
$roster_menu = new RosterMenu;
 +
print $roster_menu->makeMenu('main');
 +
 +
print
 +
'<span class="title_text">Some Title</span><br />'.
 +
$roster_login->getMessage().
 +
$roster_login->getLoginForm();
 +
 +
include_once (ROSTER_BASE . 'roster_footer.tpl');
 +
exit();
 +
}
 +
else
 +
{
 +
// continue with addon processing
 +
}
 +
// ----[ End Check log-in ]---------------------------------</php>
 +
* <span style="color:maroon;">$roster_login</span> - Roster Login class
 +
* <span style="color:maroon;">$roster_login</span>->getAuthorized() - (int) Returns the id of access
 +
** 1 - Guild Memeber Access
 +
** 2 - Officer Access
 +
** 3 - Roster Admin Access
 +
* <span style="color:maroon;">$roster_login</span>->getMessage() - (string) Message sent from Roster Login, such as "Logged In", "Logged Out", or "Wrong Password"
 +
* <span style="color:maroon;">$roster_login</span>->getLoginForm() - (string) The Roster Log-in form
 +
 +
 +
 +
====Addon Credits====
 +
Link = http://[www.someurl.net]/roster/?p=credits (SEO: http://[www.someurl.net]/roster/credits.html)<br>
 +
To get credits on the main credit page, set the $credits array in the AddOn's install.def.php file
 +
<php>var $credits = array(
 +
array( "name"=> "Author Name",
 +
"info"=> "Extra Info"),
 +
);</php>
 +
Replace the following
 +
*"Addon Name" with your addon's name
 +
*"Author Name" with your (The addon's author) name
 +
*"Extra Info" with a short description or additional info
 +
(Use <nowiki><br></nowiki> for line breaks)
 +
 +
You can add multiple arrays inside the main one to add more credits<br>
 +
(Try not to add too many, we don't wanna clutter the credits page now do we?)
 +
 +
 +
 +
====Tooltips====
 +
<php>/**
 +
* Makes a tootip and places it into the tooltip array
 +
*
 +
* @param string $var
 +
* @param string $content
 +
*/
 +
function setTooltip( $var , $content )</php>
 +
Creates a js variable for use with overlib<br>
 +
Instead of outputting text in the html, you can create a js variable that holds this instead
 +
<php>/**
 +
* Easy all in one function to make overlib tooltips
 +
* Creates a string for insertion into any html tag that has "onmouseover" and "onmouseout" events
 +
*
 +
* @param string $tooltip | Tooltip as a string (delimited by "\n" character)
 +
* @param string $caption | (optional) Text to set as a true OverLib caption
 +
* @param string $caption_color | (optional) Color for the caption
 +
* Default is 'ffffff' - white
 +
* @param bool $mode| (optional) Options 0=colorize,1=clean,2=pass through
 +
* Default 0 (colorize)
 +
* @param string $locale | Locale so color parser can work correctly
 +
* Only needed when $colorize is true
 +
* Default is $roster_conf['roster_lang']
 +
* @param string $extra_parameters | (optional) Extra OverLib parameters you wish to pass
 +
* @return unknown
 +
*/
 +
function makeOverlib( $tooltip , $caption='' , $caption_color='' , $mode=0 , $locale='' , $extra_parameters='' )</php>
 +
Returns this string for use in any html tag that supports onmouseover and onmouseout events
 +
<pre>onmouseover="return overlib(overlib_'.$num_of_tips.$caption.$extra_parameters.');" onmouseout="return nd();"</pre>
 +
For more info about makeOverlib() and its supporting functions, look at functions.lib.php
 +
 +
 +
 +
====Message Boxes====
 +
Functions to draw message boxes
 +
<php>/**
 +
* Draw a message box with the specified border color.
 +
*
 +
* @param string $message | The message to display inside the box
 +
* @param string $title | The box title
 +
* @param string $style | The border style
 +
* @return string $html | The HTML for the messagebox
 +
*/
 +
function messagebox($message, $title = 'Message', $style = 'sgray')</php>
 +
 +
<php>/**
 +
* Draw a 300x550px scrolling messagebox with the specified border color.
 +
*
 +
* @param string $message | The message to display inside the box
 +
* @param string $title | The box title
 +
* @param string $style | The border style
 +
* @param string $width | Initial width with unit
 +
* @param string $height | Initial height with unit
 +
* @return string $html | The HTML for the messagebox
 +
*/
 +
function scrollbox($message, $title = 'Message', $style = 'sgray', $width = '550px', $height = '300px')</php>
 +
 +
<php>/**
 +
* Draw a message box with the specified border color.
 +
*
 +
* @param string $message | The message to display inside the box
 +
* @param string $title | The box title
 +
* @param string $style | The border style
 +
* @param boolean $open | True if initially open
 +
* @param string $width | Initial width with unit
 +
* @return string $html | The HTML for the messagebox
 +
*/
 +
function messageboxtoggle($message, $title = 'Message', $style = 'sgray', $open = false, $width = '550px')</php>
 +
 +
<php>/**
 +
* Draw a 300x550px scrolling messagebox with the specified border color.
 +
*
 +
* @param string $messages | The message to display inside the box
 +
* @param string $title | The box title
 +
* @param string $style | The border style
 +
* @param string $width | Initial width with unit
 +
* @param string $height | Initial height with unit
 +
* @return string $html | The HTML for the messagebox
 +
*/
 +
function scrollboxtoggle($message, $title = 'Message', $style = 'sgray', $open = false, $width = '550px', $height = '300px')</php>
  
 
[[Category:RosterAddon]]
 
[[Category:RosterAddon]]

Revision as of 03:52, 22 May 2007

WR.net

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

Geographylogo.png Languages: 

English

Main Page

Contents


WoWRoster v1.8.0 AddOn Development

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

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

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


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


Download the Roster AddOnSDK



Certified WoWRoster AddOn

Certified WoWRoster AddOn

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


Requirements for Approval

Personal tools
Namespaces
Variants
Actions
WoWRoster
Navigation
Toolbox