|
|
(3 intermediate revisions by one user not shown) |
Line 1: |
Line 1: |
− | __NOEDITSECTION__
| + | #REDIRECT [[AddonSDK]] |
− | {{Disclaimer}}
| + | |
− | {{MainMenu|Roster}}
| + | |
− | | + | |
− | =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<br />
| + | |
− | And Everyone involved in the project.
| + | |
− | | + | |
− | | + | |
− | '''Download the [http://www.wowroster.net/Downloads/details/id=32.html Roster AddOnSDK]'''
| + | |
− | | + | |
− | | + | |
− | | + | |
− | | + | |
− | ==Certified WoWRoster AddOn==
| + | |
− | [[Image:Certaddon.png|frame|Certified WoWRoster AddOn]]
| + | |
− | AddOns that conform to our [[CodingStandards|Coding Standards]] and the basic outline described within this document, will be given a "<span style="color:maroon;">AddOn Framework Standards Compliant</span>" stamp of approval.
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Requirements for Approval===
| + | |
− | * Unique naming of variables in conf.php
| + | |
− | *: <php>$addon_conf['addon_name']['variable_name']</php>
| + | |
− | *: or
| + | |
− | *: <php>$addonname_variablename</php>
| + | |
− | *: This prevents each AddOns' variables from overwriting other AddOns' variables
| + | |
− | * Unique locale variables
| + | |
− | ** Use Roster base locale strings whenever possible
| + | |
− | ** Don't overwrite existing locale strings
| + | |
− | **: Roster has some protection against this, but AddOns can still overwrite other AddOns' strings
| + | |
− | * Create AddOns with SQL Debug Output, Debug Mode, and SQL Window enabled in [[Roster:CP|RosterCP]]
| + | |
− | ** Even though php notices and warnings are suppressed when these are off, it is good practice to enable these options when coding AddOns
| + | |
− | * No funky text (BOM characters displaying above the menu for example)
| + | |
− | *: (ie: strange characters appearing on top of the roster's menu)
| + | |
− | * Valid XHTML 1.0 Transitional - http://validator.w3.org
| + | |
− | * Proper use of the DB layer - <span style="color:maroon;">$roster->db</span>
| + | |
− | * Roster main files are not edited
| + | |
− | * Roster main database tables are not edited, unless you provide a clean way to revert the data in your uninstall
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==Basics of an AddOn==
| + | |
− | The following are required to run the WoWRoster back-end and to be able to run any AddOns<br>
| + | |
− | >[[Roster:Requirements|Roster Requirements]]<
| + | |
− | | + | |
− | The AddOn system is designed so that you can mod the roster base without having to change the base code as it could change a lot between versions.<br>
| + | |
− | Hopefully with this system we will be closer to having a drop-in module system without having to mod a lot of the base files each time.
| + | |
− | | + | |
− | We will be constantly refining the system as we go along.<br>
| + | |
− | So with each new version of Roster, some AddOns may break (not work in the new WoWRoster)
| + | |
− | | + | |
− | <div style="margin:5px 0 5px 0;">
| + | |
− | {| width="100%" style="clear:both;border:2px inset #ff3300;border-collapse:collapse;padding:0.2em;margin:0;margin:0 1px;"
| + | |
− | |- valign="top" style="background:#FFEBE6"
| + | |
− | |style="width:25px;padding-left:0.5em;"|[[Image:Tools clipart.png|20px]]
| + | |
− | |style="width:10px;white-space:nowrap;padding:4px 1em 0 0.5em;border-right:1px solid #ff3300;"|'''Important:'''
| + | |
− | |style="padding:1px 1em 0;background:#F6F9ED;"|
| + | |
− | DO NOT use php short tags in your php files<br>
| + | |
− | This is also stated in the [[CodingStandards|WoWRoster Coding Standards]]<br>
| + | |
− | <span style="color:red;">NO!</span> <code><? ?></code><br>
| + | |
− | <span style="color:green;">YES</span> <code><?php ?></code><br>
| + | |
− | <span style="color:red;">NO!</span> <code><?=$var; ?></code><br>
| + | |
− | <span style="color:green;">YES</span> <code><?php echo $var; ?></code><br>
| + | |
− | Use the "long tags" as the short ones can break web servers with short_tags set to "off"
| + | |
− | |}
| + | |
− | </div>
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==Changes Since 1.7.3==
| + | |
− | * All AddOns need to be installed using an install definition file 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
| + | |
− | | + | |
− | | + | |
− | ==AddOn Framework==
| + | |
− | | + | |
− | ===Features===
| + | |
− | # Uses output buffering, which means all the output is stored in a variable that is sent to the browser
| + | |
− | # Do not have to include Roster's conf.php
| + | |
− | # Do not have to include/declare <span style="color:maroon;">$roster</span> object
| + | |
− | # Do not have to connect to Roster's database
| + | |
− | # Do not have to include your conf.php
| + | |
− | # 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
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===What it does===
| + | |
− | # Includes all Roster config variables for you to use (<span style="color:maroon;">$roster</span>->config)
| + | |
− | # Includes all Roster SQL functions for your use (<span style="color:maroon;">$roster</span>->db)
| + | |
− | # Includes all Roster and AddOn language variables for you (<span style="color:maroon;">$roster</span>->locale->wordings, <span style="color:maroon;">$roster</span>->locale->act)
| + | |
− | # Includes all Roster css styles
| + | |
− | # The Roster header, footer, and menu are included to your files.
| + | |
− | #: These can be disabled if needed, more below...
| + | |
− | | + | |
− | Best of all, this is transparent to you!
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===AddOn Directory Structure===
| + | |
− | Here is an example of an AddOn's directory structure
| + | |
− | <pre>roster/
| + | |
− | |_ addons/
| + | |
− | |_ addonname/
| + | |
− | |_ admin/
| + | |
− | | |_ index.php
| + | |
− | | |_ other.php
| + | |
− | |
| + | |
− | |_ char/
| + | |
− | | |_ index.php
| + | |
− | | |_ other.php
| + | |
− | |
| + | |
− | |_ guild/
| + | |
− | | |_ index.php
| + | |
− | | |_ other.php
| + | |
− | |
| + | |
− | |_ guildless/
| + | |
− | | |_ index.php
| + | |
− | | |_ other.php
| + | |
− | |
| + | |
− | |_ inc/
| + | |
− | | |_ functions.php
| + | |
− | |
| + | |
− | |_ locale/
| + | |
− | | |_ deDE.php
| + | |
− | | |_ enUS.php
| + | |
− | | |_ esES.php
| + | |
− | | |_ frFR.php
| + | |
− | |
| + | |
− | |_ realm/
| + | |
− | | |_ index.php
| + | |
− | | |_ other.php
| + | |
− | |
| + | |
− | |_ conf.php
| + | |
− | |_ index.php
| + | |
− | |_ install.def.php
| + | |
− | |_ somefile.php
| + | |
− | |_ update_hook.php
| + | |
− | |_ util.php
| + | |
− | </pre>
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====admin Folder====
| + | |
− | The admin folder houses files for the Roster CP
| + | |
− | Normally you'll never need files here because the Config API can handle most configuration needs
| + | |
− | | + | |
− | If you do need a custom config interface, this is where you make it
| + | |
− | | + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-addonname-file
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/addonname/file.html
| + | |
− | {{Note|The File parameter is optional}}
| + | |
− | | + | |
− | This will normally grab your AddOn's config data from the 'roster_addon_config' table in the database and display the options using the Config API
| + | |
− | | + | |
− | If you need your own file, you need only to place index.php in addons/addonname/admin/
| + | |
− | | + | |
− | You can also have the best of both worlds<br>
| + | |
− | For example, the Members List and Character Info AddOns use both the Config API and custom files
| + | |
− | * Members List uses addons/memberslist/admin/update.php to process data for alt relations
| + | |
− | *: Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-memberslist-update
| + | |
− | *: SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/memberslist/update.html
| + | |
− | * Character Info uses addons/info/admin/display.php to control data display for each character
| + | |
− | *: Normal Link - http://[www.someurl.net]/roster/trunk/?p=rostercp-addon-info-display
| + | |
− | *: SEO Link - http://[www.someurl.net]/roster/trunk/rostercp/addon/info/display.html
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====char Folder====
| + | |
− | Files for use in the Character scope<br>
| + | |
− | Data for the requested character is passed to the AddOn<br>
| + | |
− | If member= is not specified or if this member does not exist, an error message will display
| + | |
− | | + | |
− | member= can be either the member id number, or name@realm text
| + | |
− | | + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=##
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname&member=name@realm
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=##.html
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/member=name@realm.html
| + | |
− | | + | |
− | Accessing other files in the char scope is easy<br>
| + | |
− | addons/addonname/addonname/char/file.php is accessed like this:
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=char-addonname-file&member=##
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/char/addonname/file/member=##.html
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====guild Folder====
| + | |
− | Files for use in the Guild scope<br>
| + | |
− | Data for the requested guild is passed to the AddOn<br>
| + | |
− | If guild= is not specified, the default guild/realm name set in Roster CP will show<br>
| + | |
− | If the guild does not exist or if there is no data for this guild, an error message will display
| + | |
− | | + | |
− | guild= can be either the guild id number, or name@realm text
| + | |
− | | + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=##
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&guild=name@realm
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=##.html
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/guild=name@realm.html
| + | |
− | | + | |
− | Accessing other files in the guild scope is easy<br>
| + | |
− | addons/addonname/guild/file.php is accessed like this:
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname-file&guild=##
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/file/guild=##.html
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====guildless Folder====
| + | |
− | Files for use in the Guildless scope<br>
| + | |
− | Data for the requested realm is passed to the AddOn<br>
| + | |
− | If realm= is not specified, the default realm name set in Roster CP will show<br>
| + | |
− | If the realm does not exist or if there is no data for this realm, an error message will display
| + | |
− | | + | |
− | realm= can be text
| + | |
− | | + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=guildless-addonname&realm=name
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/guildless/addonname/realm=name.html
| + | |
− | | + | |
− | Accessing other files in the guildless scope is easy<br>
| + | |
− | addons/addonname/guildless/file.php is accessed like this:
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=guildless-addonname-file&realm=name
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/guildless/addonname/file/realm=name.html
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====inc Folder====
| + | |
− | Other folders that house files not meant for direct access by the AddOn Framework<br>
| + | |
− | This does not necessarily need to be called inc<br>
| + | |
− | It can be lib, library, functions, etc...
| + | |
− | | + | |
− | Place any files here that you do not or should not be accessed directly by the AddOn Framework
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====locale Folder====
| + | |
− | Where locale translation files go<br>
| + | |
− | See below for more info [[#Locale Files|Locale Files]]
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====realm Folder====
| + | |
− | Files for use in the Realm scope<br>
| + | |
− | Data for the requested realm is passed to the AddOn<br>
| + | |
− | If realm= is not specified, the default realm name set in Roster CP will show<br>
| + | |
− | If the realm does not exist or if there is no data for this realm, an error message will display
| + | |
− | | + | |
− | realm= can be text
| + | |
− | | + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=guild-addonname&realm=name
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/guild/addonname/realm=name.html
| + | |
− | | + | |
− | Accessing other files in the realm scope is easy<br>
| + | |
− | addons/addonname/realm/file.php is accessed like this:
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=realm-addonname-file&realm=name
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/realm/addonname/file/realm=name.html
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====Other Files and the util Scope====
| + | |
− | Files not in these folders are considered under the util scope<br>
| + | |
− | This scope is not restricted if there is no guild or character information and can be accessed before data is in the database
| + | |
− | | + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname.html
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname.html
| + | |
− | | + | |
− | Accessing other files in the util scope is easy<br>
| + | |
− | addons/addonname/file.php is accessed like this:
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/trunk/?p=util-addonname-file
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/trunk/util/addonname/file.html
| + | |
− | Note that conf.php, install.def.php, and update_hook.php cannot be access this way
| + | |
− | | + | |
− | * conf.php - This is included before any other addon file, any initialization can be done here
| + | |
− | * index.php - The main file for the util scope
| + | |
− | * [[#Creating_the_Installer|install.def.php]] - The AddOn's install/upgrade/uninstall definition file
| + | |
− | * [[#CSS_Styles|style.css]] - A custom css style for the AddOn
| + | |
− | * [[#AddOn_Update_Hook|update_hook.php]] - Update Hook file
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Required Files===
| + | |
− | There are a few files that you must have
| + | |
− | * [[#Creating_the_Installer|addons/addoname/install.def.php]] (AddOn install/upgrade/uninstall file)
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Linking to AddOns===
| + | |
− | You can link to any file in the AddOn folder (except conf.php, install.def.php, and update_hook.php)
| + | |
− | | + | |
− | The url to access each page is simple
| + | |
− | * Normal Link - http://[www.someurl.net]/roster/?p=scope-addonname-file
| + | |
− | * SEO Link - http://[www.someurl.net]/roster/scope/addonname/file.html
| + | |
− | {{Note|"file" is optional}}
| + | |
− | | + | |
− | The values explained
| + | |
− | * scope - One of five values; realm, guildless, guild, char, util
| + | |
− | *: Realm (realm) - Page that uses realm information (realm=name is appended to the url)
| + | |
− | *: GuildLess (guildless) - Page that uses realm information for unguilded data (realm=name is appended to the url)
| + | |
− | *: Guild (guild) - Page that uses guild information (guild=id# or guild=name@server is appended to the url)
| + | |
− | *: Character (char) - Page that uses character information (member=id# or member=name@server must be appended to the url)
| + | |
− | *: Utility (util) - Page that doesn't use either, or could use either, most of the Roster pages are utility pages (rostercp, update, credits, search)
| + | |
− | * addonname - The name of the AddOn you are accessing
| + | |
− | * file - The file you are accessing
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==Creating the Installer==
| + | |
− | This installer requires a similar install file definition as DragonFly CMS, with
| + | |
− | some important exceptions:
| + | |
− | * SQL entries are the same as as passing it to mysql_query() using <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>)
| + | |
− | * No rollback data per query. Instead, call <span style="color:maroon;">$installer</span>->add_backup(<span style="color:maroon;">$table_name</span>) for each table you want restored in case of an upgrade/uninstall failure.
| + | |
− | *: Any backup tables you create are automatically deleted in rollback.
| + | |
− | * Different required variables to be set.
| + | |
− | | + | |
− | You should create a file called install.def.php with in it a class that is named identical to your AddOn's install directory name.<br>
| + | |
− | This name will be referred to as your AddOn's basename.
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Properties===
| + | |
− | * var <span style="color:maroon;">$active</span>
| + | |
− | *: Boolean, set to true to activate this AddOn after installing, set to false if it has to be configured first.
| + | |
− | | + | |
− | * var <span style="color:maroon;">$version</span>
| + | |
− | *: String, the current version of your AddOn.
| + | |
− | *: Needs to be compatible with php's version_compare().
| + | |
− | *: Should be incremented on every update that includes a database update, or any update if you wish.
| + | |
− | | + | |
− | * var <span style="color:maroon;">$icon</span>
| + | |
− | *: String, an icon to display for your AddOn in the AddOn management page in RosterCP
| + | |
− | *: Valid icons are from the Interface ImagePack
| + | |
− | | + | |
− | * var <span style="color:maroon;">$fullname</span>
| + | |
− | *: String, the full name of the AddOn for display.
| + | |
− | | + | |
− | * var <span style="color:maroon;">$description</span>
| + | |
− | *: String, a sort description of your AddOn.
| + | |
− | | + | |
− | * var <span style="color:maroon;">$credits</span>
| + | |
− | *: Credits information.
| + | |
− | <php>$credits = array(
| + | |
− | array( "name"=> "Name",
| + | |
− | "info"=> "Some Info"),
| + | |
− | array( "name"=> "Another Name",
| + | |
− | "info"=> "More Info"),
| + | |
− | );</php>
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Methods===
| + | |
− | * install()
| + | |
− | *: Here you can add all queries for a fresh install.
| + | |
− | *: No parameters.
| + | |
− | *: Return true on success, false on failure.
| + | |
− | | + | |
− | * upgrade(<span style="color:maroon;">$oldversion</span>)
| + | |
− | *: Here you can add all queries for an upgrade.
| + | |
− | *:: <span style="color:maroon;">$oldversion</span>, the version you are upgrading from.
| + | |
− | *: Return true on success, false on failure.
| + | |
− | {{Note|You should supply your own file to be called for upgrades of a Roster 1.7.x AddOn since Roster 1.8 cannot detect these AddOns.}}
| + | |
− | | + | |
− | * uninstall()
| + | |
− | *: Here you should add all queries for an uninstall.
| + | |
− | *: No parameters.
| + | |
− | *: Return true on success, false on failure
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Adding Queries===
| + | |
− | Queries are added to the install using the <span style="color:maroon;">$installer</span> methods.
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->add_query(<span style="color:maroon;">$sqlstring</span>);
| + | |
− | *: Any valid SQL query
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->add_backup(<span style="color:maroon;">$table</span>)
| + | |
− | *: Makes a temporary copy of a table and its contents that is put back in case of a rollback
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->add_drop(<span style="color:maroon;">$table</span>)
| + | |
− | *: Have a table be dropped on rollback
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->add_config(<span style="color:maroon;">$sqlstring</span>);
| + | |
− | *: Add config sql to `roster_addon_config` table
| + | |
− | *: Format is "'id','config_name','config_value','form_type','config_type'"
| + | |
− | *: These entries will be used to build a config page through Roster's config page API
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Creating/Editing Menu Entries===
| + | |
− | There are 3 separate functions for this.<br>
| + | |
− | Note the title should be unique per AddOn.
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->add_menu_button(<span style="color:maroon;">$title</span>, <span style="color:maroon;">$scope</span>, <span style="color:maroon;">$url</span>, <span style="color:maroon;">$icon</span>)
| + | |
− | *: Adds a menu button. Parameters:
| + | |
− | *: <span style="color:maroon;">$title</span>
| + | |
− | *:: The localization key for the menu button's title.
| + | |
− | *: <span style="color:maroon;">$scope</span>
| + | |
− | *:: The scope of the link ('util','realm','guild','guildless','char')
| + | |
− | *: <span style="color:maroon;">$url</span>
| + | |
− | *:: The url parameters this button should call the AddOn with
| + | |
− | *: <span style="color:maroon;">$icon</span>
| + | |
− | *:: An icon to display in the button
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->update_menu_button($title, $scope, $url, $icon)
| + | |
− | *: Changes menu button. Parameters:
| + | |
− | *: <span style="color:maroon;">$title</span>
| + | |
− | *:: The localization key for the menu button's title.
| + | |
− | *: <span style="color:maroon;">$scope</span>
| + | |
− | *:: The scope of the link ('util','realm','guild','guildless','char')
| + | |
− | *: <span style="color:maroon;">$url</span>
| + | |
− | *:: The url parameters this button should call the AddOn with
| + | |
− | *: <span style="color:maroon;">$icon</span>
| + | |
− | *:: An icon to display in the button
| + | |
− | | + | |
− | * <span style="color:maroon;">$installer</span>->remove_menu_button($title)
| + | |
− | *: Removes a menu button. Parameters:
| + | |
− | *: <span style="color:maroon;">$title</span>
| + | |
− | *:: The localization key for the menu button's title.
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Example File===
| + | |
− | Here is an example of an AddOn install file<br>
| + | |
− | From the "Keys" AddOn
| + | |
− | | + | |
− | You can find more examples in the addons/ folder in roster
| + | |
− | <php><?php
| + | |
− | /**
| + | |
− | * WoWRoster.net WoWRoster
| + | |
− | *
| + | |
− | * LICENSE: Licensed under the Creative Commons
| + | |
− | * "Attribution-NonCommercial-ShareAlike 2.5" license
| + | |
− | *
| + | |
− | * @copyright 2002-2007 WoWRoster.net
| + | |
− | * @license http://creativecommons.org/licenses/by-nc-sa/2.5 Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
| + | |
− | * @version SVN: $Id: install.def.php 897 2007-05-06 00:35:11Z Zanix $
| + | |
− | * @link http://www.wowroster.net
| + | |
− | * @package InstanceKeys
| + | |
− | * @subpackage Installer
| + | |
− | */
| + | |
− | | + | |
− | if ( !defined('ROSTER_INSTALLED') )
| + | |
− | {
| + | |
− | exit('Detected invalid access to this file!');
| + | |
− | }
| + | |
− | | + | |
− | /**
| + | |
− | * Installer Instance Keys Addon
| + | |
− | *
| + | |
− | * @package InstanceKeys
| + | |
− | * @subpackage Installer
| + | |
− | */
| + | |
− | class keys
| + | |
− | {
| + | |
− | var $active = true;
| + | |
− | var $icon = 'inv_misc_key_06';
| + | |
− | | + | |
− | var $upgrades = array(); // There are no previous versions to upgrade from
| + | |
− | | + | |
− | var $version = '1.8.0.0';
| + | |
− | | + | |
− | var $fullname = 'Instance Keys';
| + | |
− | var $description = 'Lists Azeroth Dungeon keys for Members';
| + | |
− | var $credits = array(
| + | |
− | array( "name"=> "WoWRoster Dev Team",
| + | |
− | "info"=> "Original Author")
| + | |
− | );
| + | |
− | | + | |
− | | + | |
− | /**
| + | |
− | * Install Function
| + | |
− | *
| + | |
− | * @return bool
| + | |
− | */
| + | |
− | function install()
| + | |
− | {
| + | |
− | global $installer;
| + | |
− | | + | |
− | // Master and menu entries
| + | |
− | $installer->add_config("'1','startpage','keys_conf','display','master'");
| + | |
− | $installer->add_config("'110','keys_conf',NULL,'blockframe','menu'");
| + | |
− | | + | |
− | $installer->add_config("'1010','colorcmp','#00ff00','color','keys_conf'");
| + | |
− | $installer->add_config("'1020','colorcur','#ffd700','color','keys_conf'");
| + | |
− | $installer->add_config("'1030','colorno','#ff0000','color','keys_conf'");
| + | |
− | | + | |
− | $installer->add_menu_button('keys','guild');
| + | |
− | return true;
| + | |
− | }
| + | |
− | | + | |
− | /**
| + | |
− | * Upgrade Function
| + | |
− | *
| + | |
− | * @param string $oldversion
| + | |
− | * @return bool
| + | |
− | */
| + | |
− | function upgrade($oldversion)
| + | |
− | {
| + | |
− | // Nothing to upgrade from yet
| + | |
− | return false;
| + | |
− | }
| + | |
− | | + | |
− | /**
| + | |
− | * Un-Install Function
| + | |
− | *
| + | |
− | * @return bool
| + | |
− | */
| + | |
− | function uninstall()
| + | |
− | {
| + | |
− | global $installer;
| + | |
− | | + | |
− | $installer->remove_all_config();
| + | |
− | | + | |
− | $installer->remove_menu_button('keys');
| + | |
− | return true;
| + | |
− | }
| + | |
− | }</php>
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==Roster Config API==
| + | |
− | This is the current functionality of the Roster Config API.<br>
| + | |
− | There are two classes of form types:
| + | |
− | * Option blocks for layout
| + | |
− | * Actual options
| + | |
− | Items of the page, pageframe, and pagehide class contain option blocks.<br>
| + | |
− | Items of the blockframe or blockhide class contain options.
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Menu Bar Items===
| + | |
− | * page, pageframe, pagehide, blockframe, blockhide:
| + | |
− | *: A page of options that gets selected with javascript
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'110','config_name',NULL,'blockframe','menu'")
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'150', 'config_name', NULL, 'page{1', 'menu'")
| + | |
− | | + | |
− | * link
| + | |
− | *: An external link to be opened in the same window
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("120,'config_name','link_value','link','menu'")
| + | |
− | | + | |
− | * newlink
| + | |
− | *: An external link to be opened in a new window
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("170,'config_name','<nowiki>http://www.someurl.com</nowiki>','newlink','menu'")
| + | |
− | | + | |
− | * makelink
| + | |
− | *: Passes this through Roster's makelink() function to generate a correct link to another page in Roster.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("120,'config_name','link_value','makelink','menu'")
| + | |
− | | + | |
− | * makenewlink
| + | |
− | *: Same as makelink, except it opens a new browser window.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("180,'config_name','link_value','makenewlink','menu'")
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Options Blocks===
| + | |
− | * page{n
| + | |
− | *: n columns of options blocks
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4001', 'menu_conf_wide', NULL, 'page{2', 'menu_conf'")
| + | |
− | | + | |
− | * pageframe{n
| + | |
− | *: n columns of options blocks in a border
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4025', 'menu_conf_left', NULL, 'pageframe{3', 'menu_conf'")
| + | |
− | | + | |
− | * pagehide{n
| + | |
− | *: n columns of options blocks in a border, with a show/hide option
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4020', 'menu_conf_hidden', NULL, 'pagehide{1', 'menu_conf'")
| + | |
− | | + | |
− | * blockframe
| + | |
− | *: A list of options in a border
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4000, 'menu_conf_top', NULL, 'blockframe', 'menu_conf'")
| + | |
− | | + | |
− | * blockhide
| + | |
− | *: A list of options in a border, with a show/hide option
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4050, 'menu_conf_bottom', NULL, 'blockhide', 'menu_conf'")
| + | |
− | | + | |
− | * function{name
| + | |
− | *: Calls the function called name with no parameters to produce the HTML for the page.
| + | |
− | *: If this is a tab (directly linked from the switch menu on the left side) it is put outside the main form so you can put forms in it.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4470', 'menu_conf_right', NULL, 'function{newForm', 'menu_conf_top'")
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Options===
| + | |
− | * text{n|m
| + | |
− | *: A text box m characters wide, maximum of n characters input
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'1110','page_size','0','text{4|30','menu_conf_top'")
| + | |
− | | + | |
− | * radio{op1^val1|op2^val2|op3^val3...
| + | |
− | *: A list of radio buttons with labels op1, op2, op3,...
| + | |
− | *: Which produce values val1, val2, val3,...
| + | |
− | *: Labels are literal, not localization keys.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'1010','nojs','0','radio{Server^1|Client^0','menu_conf_top'")
| + | |
− | | + | |
− | * select{op1^val1|op2^val2|op3^val3...
| + | |
− | *: A dropdown box with options op1, op2, op3,...
| + | |
− | *: Which produce values val1, val2, val3,...
| + | |
− | *: Labels are literal, not localization keys.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'1020','def_sort','Note','select{Public Note^Note|Officer Note^OfficerNote','menu_conf_top'")
| + | |
− | | + | |
− | * function{name
| + | |
− | *: Calls the function called name with the option record as parameter to produce the HTML for the option.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4270', 'left_text', 'VERANDA.TTF', 'function{fontFiles', 'menu_conf_top'")
| + | |
− | | + | |
− | * display
| + | |
− | *: Displays the option's setting.
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'3, 'help_text', 'This is to help', 'display', 'menu_conf_top'")
| + | |
− | | + | |
− | * color
| + | |
− | *: Enables the use of the color picker javascript to pick a color from a pallet
| + | |
− | *: <span style="color:maroon;">$installer</span>->add_config("'4230', 'menu_left_barcolor', '#3e0000', 'color', 'menu_conf_top'")
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===AddOn Config Function File===
| + | |
− | addons/addonname/admin/config.func.php
| + | |
− | *: Both function types call functions that can be defined in a file called 'config.func.php' in your AddOn's admin/ directory.
| + | |
− | *: If this file has a function named topBox(), the html returned by this function will be put above the options in the middle column.
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==Locale Files==
| + | |
− | These are used in translating any text in your AddOn if you want to support multi-langages.<br>
| + | |
− | As you can see in the example below, we have a file for deDE which is the German language, enUS which is the English language, frFR for French, and esES for Spanish.
| + | |
− | | + | |
− | Roster currently supports deDE, enUS, frFR, and esES, these are taken out of character profiler based on what region of WOW they are using.
| + | |
− | | + | |
− | The folder structure for locale files is as follows:
| + | |
− | <pre>roster/
| + | |
− | |_ addons/
| + | |
− | |_ addonname/
| + | |
− | |_ locale/
| + | |
− | |_ deDE.php
| + | |
− | |_ enUS.php
| + | |
− | |_ esES.php
| + | |
− | |_ frFR.php</pre>
| + | |
− | When using locale files, it is absolutely necessary to ALWAYS have enUS.php<br>
| + | |
− | The AddOn Framework will default to this file if a locale is not found for a specific locale
| + | |
− | | + | |
− | Example:
| + | |
− | * You make an AddOn and only create it in English (enUS.php only, no other locale files)
| + | |
− | * Someone downloads your AddOn for a deDE Roster
| + | |
− | * The AddOn Framework automatically inserts the enUS locale strings into the deDE locale
| + | |
− | * This way, you only need to have enUS.php
| + | |
− | * Later, if other locales are translated, they can be placed into the locale folder and Roster will detect them based on the locales set in localization/languages.php
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Using Locale Strings===
| + | |
− | When using these them in your script you can use something similar to this
| + | |
− | <php>$header_title = $roster->locale->wordings['locale_key']['some_key'];</php>
| + | |
− | or
| + | |
− | <php>$header_title = $roster->locale->act['some_key'];</php>
| + | |
− | The first example is to get a specific locale value<br>
| + | |
− | The second is a reference to the current locale set in Roster
| + | |
− | | + | |
− | Remember that Roster's locale files are already added, so you only have to add the stuff that is custom to your AddOn.
| + | |
− | | + | |
− | So if you need to check to make sure we have don't already have a translation, you can open the files in the "localization/" directory to see the default words that you don't have to duplicate.
| + | |
− | | + | |
− | Duplication may cause errors in the main Roster code, if you duplicate a main Roster locale variable, you will incur the wrath of the WoWRoster.net Dev Team
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Example File===
| + | |
− | Example from the PvPLog Roster AddOn<br>
| + | |
− | addons/questlist/locale/deDE.php
| + | |
− | <php><?php
| + | |
− | /**
| + | |
− | * WoWRoster.net WoWRoster
| + | |
− | *
| + | |
− | * LICENSE: Licensed under the Creative Commons
| + | |
− | * "Attribution-NonCommercial-ShareAlike 2.5" license
| + | |
− | *
| + | |
− | * @copyright 2002-2007 WoWRoster.net
| + | |
− | * @license http://creativecommons.org/licenses/by-nc-sa/2.5 Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
| + | |
− | * @version SVN: $Id: deDE.php 899 2007-05-06 10:16:36Z Zanix $
| + | |
− | * @link http://www.wowroster.net
| + | |
− | */
| + | |
− | | + | |
− | $lang['bglog']='BG Übersicht';
| + | |
− | $lang['pvplog']='PvP Übersicht';
| + | |
− | $lang['duellog']='Duell Übersicht';
| + | |
− | $lang['duelsummary']='Duell Summary';
| + | |
− | | + | |
− | $lang['totalwins']='Gewinne total';
| + | |
− | $lang['totallosses']='Verluste total';
| + | |
− | $lang['totaloverall']='Gesamt';
| + | |
− | $lang['win_average']='Durchschnittliche Level Differenz (Gewinne)';
| + | |
− | $lang['loss_average']='Durchschnittliche Level Differenz (Verluste)';
| + | |
− | | + | |
− | // These need to be EXACTLY what PvPLog stores them as
| + | |
− | $lang['alterac_valley']='Alteractal';
| + | |
− | $lang['arathi_basin']='Arathibecken';
| + | |
− | $lang['warsong_gulch']='Kriegshymnenschlucht';
| + | |
− | | + | |
− | $lang['world_pvp']='Welt-PvP';
| + | |
− | $lang['versus_guilds']='Gegengilden';
| + | |
− | $lang['versus_players']='Gegenspieler';
| + | |
− | $lang['bestsub']='Beste Subzone';
| + | |
− | $lang['worstsub']='Schlechteste Subzone';
| + | |
− | $lang['killedmost']='Am meisten getötet';
| + | |
− | $lang['killedmostby']='Am meisten getötet durch';
| + | |
− | $lang['gkilledmost']='Am meisten getötete Spieler der Gilde';
| + | |
− | $lang['gkilledmostby']='Am meister getötet durch Spieler der Gilde';
| + | |
− | | + | |
− | $lang['wins']='Gewinne';
| + | |
− | $lang['losses']='Verluste';
| + | |
− | $lang['overall']='Gesamt';
| + | |
− | $lang['best_zone']='Beste Zone';
| + | |
− | $lang['worst_zone']='Schlechteste Zone';
| + | |
− | $lang['most_killed']='Meisten getötet';
| + | |
− | $lang['most_killed_by']='Meisten getötet durch';
| + | |
− | $lang['leveldiff']='LevelDiff';
| + | |
− | $lang['bg']='Schlachtfeld';
| + | |
− | $lang['kills']='Kills';
| + | |
− | | + | |
− | // guildpvp strings
| + | |
− | $lang['guildwins'] = 'Wins by Guild';
| + | |
− | $lang['guildlosses'] = 'Losses by Guild';
| + | |
− | $lang['enemywins'] = 'Wins by Enemy';
| + | |
− | $lang['enemylosses'] = 'Losses by Enemy';
| + | |
− | $lang['purgewins'] = 'Guild Member Kills';
| + | |
− | $lang['purgelosses'] = 'Guild Member Deaths';
| + | |
− | $lang['purgeavewins'] = 'Best Win/Level-Diff Average';
| + | |
− | $lang['purgeavelosses'] = 'Best Loss/Level-Diff Average';
| + | |
− | $lang['pvpratio'] = 'Solo Win/Loss Ratios';
| + | |
− | $lang['playerinfo'] = 'Player Info';
| + | |
− | $lang['kill_lost_hist']='Kill/Loss history for %1$s (%2$s %3$s) of %4$s';
| + | |
− | $lang['kill_lost_hist_guild'] = 'Kill/Loss history for Guild "%1$s"';
| + | |
− | $lang['solo_win_loss'] = 'Solo Win/Loss Ratios (Level differences -7 to +7 counted)';
| + | |
− | $lang['guildinfo'] = 'Guild Info';
| + | |
− | | + | |
− | $lang['admin']['pvpconfig'] = "PvPLog Config|Configure PvPLog main options";
| + | |
− | $lang['admin']['minPvPLogver'] = "Min PvPLog version|Minimum PvPLog Version zum Upload";
| + | |
− | </php>
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==CSS Styles==
| + | |
− | CSS style from the MembersList AddOn
| + | |
− | <css>/**
| + | |
− | * WoWRoster.net WoWRoster
| + | |
− | *
| + | |
− | * LICENSE: Licensed under the Creative Commons
| + | |
− | * "Attribution-NonCommercial-ShareAlike 2.5" license
| + | |
− | *
| + | |
− | * @copyright 2002-2007 WoWRoster.net
| + | |
− | * @license http://creativecommons.org/licenses/by-nc-sa/2.5 Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
| + | |
− | * @version SVN: $Id: style.css 942 2007-05-20 04:50:02Z Zanix $
| + | |
− | * @link http://www.wowroster.net
| + | |
− | * @package MembersList
| + | |
− | */
| + | |
− | | + | |
− | .membersRowColor1 {
| + | |
− | background-color:#1F1E1D;
| + | |
− | }
| + | |
− | | + | |
− | .membersRowColor2 {
| + | |
− | background-color:#2E2D2B;
| + | |
− | }
| + | |
− | | + | |
− | .membersRowAltColor1 {
| + | |
− | background-color:#1F1E3D;
| + | |
− | }
| + | |
− | | + | |
− | .membersRowAltColor2 {
| + | |
− | background-color:#2E2D4B;
| + | |
− | }</css>
| + | |
− | | + | |
− | I assume you know what css is...
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ==AddOn Update Hook==
| + | |
− | The update hook is a file that ties into the lua upload process<br>
| + | |
− | You can specify any additional lua files you may you need
| + | |
− | | + | |
− | There are a few hook modes that an AddOn can make use of
| + | |
− | * update
| + | |
− | ** This mode does not hook into the CharacterProfiler upload process and is a good way to parse and process data from lua files other than CharacterProfiler
| + | |
− | * char_pre
| + | |
− | ** This mode is fired before any character is processed
| + | |
− | * char
| + | |
− | ** This mode fires for every character that is processed
| + | |
− | * char_post
| + | |
− | ** This mode is fired after every character is processed
| + | |
− | * guild_pre
| + | |
− | ** This mode is fired for each guild processed before any guild members are processed
| + | |
− | * guild
| + | |
− | ** This mode is fired for each guild processed and for each guild member processed
| + | |
− | * guild_post
| + | |
− | ** This mode is fired for each guild processed after guild members are processed
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Properties===
| + | |
− | The following variables are required in the update hook class
| + | |
− | | + | |
− | * var <span style="color:maroon;">$messages</span>
| + | |
− | *: String, any messages or output.
| + | |
− | | + | |
− | * var <span style="color:maroon;">$data</span>
| + | |
− | *: Array, Addon data object, recieved in constructor.
| + | |
− | *: This holds the addon's data from the database
| + | |
− | | + | |
− | * var <span style="color:maroon;">$icon</span>
| + | |
− | *: String, an icon to display for your AddOn in the AddOn management page in RosterCP
| + | |
− | *: Valid icons are from the Interface ImagePack
| + | |
− | | + | |
− | * var <span style="color:maroon;">$files</span>
| + | |
− | *: array, An array of additional lua files that your addon needs.
| + | |
− | *: If you are using CharacterProfiler for data, there is no need to list it here.
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Methods===
| + | |
− | * addonUpdate()
| + | |
− | *: The constructor for the update hook
| + | |
− | *: This is the only required method in an update hook class
| + | |
− | *: The addons data is passed to this function, you should set the passed data to an internal property variable
| + | |
− | <php> function addonUpdate($data)
| + | |
− | {
| + | |
− | $this->data = $data;
| + | |
− | }</php>
| + | |
− | | + | |
− | The following methods are reserved for update hooks<br>
| + | |
− | Descriptions for these methods are above and are not required
| + | |
− | | + | |
− | These function fairly simmilar
| + | |
− | * update()
| + | |
− | * char_pre(<span style="color:maroon;">$characters</span>)
| + | |
− | ** <span style="color:maroon;">$characters</span> - Array: All characters and their data in CharacterProfiler.lua
| + | |
− | * char(<span style="color:maroon;">$char</span>, <span style="color:maroon;">$memberid</span>)
| + | |
− | ** <span style="color:maroon;">$char</span> - Array: Character data array for the current processed character
| + | |
− | ** <span style="color:maroon;">$memberid</span> - Int: Member id from members table
| + | |
− | * char_post(<span style="color:maroon;">$characters</span>)
| + | |
− | ** <span style="color:maroon;">$characters</span> - Array: All characters and their data in CharacterProfiler.lua
| + | |
− | * guild_pre(<span style="color:maroon;">$guild</span>)
| + | |
− | ** <span style="color:maroon;">$guild</span> - Array: All guilds and their data in CharacterProfiler.lua
| + | |
− | * guild(<span style="color:maroon;">$char</span>, <span style="color:maroon;">$memberid</span>)
| + | |
− | ** <span style="color:maroon;">$char</span> - Array: Member data array for the current processed member
| + | |
− | ** <span style="color:maroon;">$memberid</span> - Int: Member id from members table
| + | |
− | * guild_post(<span style="color:maroon;">$guild</span>)
| + | |
− | ** <span style="color:maroon;">$guild</span> - Array: All guilds and their data in CharacterProfiler.lua
| + | |
− | | + | |
− | You can add other methods or properties as you wish, but be warned that Roster may implement more update hook methods in future versions
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Example Update Hook File===
| + | |
− | This is an example update hook file<br>
| + | |
− | Look at memberslist and pvplog (example of additional lua file upload and processing) for more complex examples
| + | |
− | <php><?php
| + | |
− | /**
| + | |
− | * WoWRoster.net WoWRoster
| + | |
− | *
| + | |
− | * LICENSE: Licensed under the Creative Commons
| + | |
− | * "Attribution-NonCommercial-ShareAlike 2.5" license
| + | |
− | *
| + | |
− | * @copyright 2002-2007 WoWRoster.net
| + | |
− | * @license http://creativecommons.org/licenses/by-nc-sa/2.5 Creative Commons "Attribution-NonCommercial-ShareAlike 2.5"
| + | |
− | * @version SVN: $Id: update_hook.php 899 2007-05-06 10:16:36Z Zanix $
| + | |
− | * @link http://www.wowroster.net
| + | |
− | * @package AddOnName
| + | |
− | */
| + | |
− | | + | |
− | if ( !defined('ROSTER_INSTALLED') )
| + | |
− | {
| + | |
− | exit('Detected invalid access to this file!');
| + | |
− | }
| + | |
− | | + | |
− | /**
| + | |
− | * Addon Update class
| + | |
− | * This MUST be the same name as the addon basename
| + | |
− | */
| + | |
− | class addonUpdate
| + | |
− | {
| + | |
− | var $messages = ''; // Update messages
| + | |
− | var $data = array(); // Addon config data automatically pulled from the addon_config table
| + | |
− | var $files = array();
| + | |
− | | + | |
− | | + | |
− | /**
| + | |
− | * Class instantiation
| + | |
− | * The name of this function MUST be the same name as the class name
| + | |
− | *
| + | |
− | * @param array $data | Addon data
| + | |
− | * @return recipe
| + | |
− | */
| + | |
− | function addonUpdate($data)
| + | |
− | {
| + | |
− | $this->data = $data;
| + | |
− | }
| + | |
− | | + | |
− | /**
| + | |
− | * Resets addon messages
| + | |
− | */
| + | |
− | function reset_messages()
| + | |
− | {
| + | |
− | $this->messages = '';
| + | |
− | }
| + | |
− | | + | |
− | | + | |
− | function update()
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"green\">This is a non CP hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | }
| + | |
− | | + | |
− | function guild_pre( $data )
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"green\">This is a guild_pre hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | }
| + | |
− | | + | |
− | function guild( $data , $memberid )
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"yellow\">This is a guild hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | }
| + | |
− | | + | |
− | function guild_post( $data )
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"red\">This is a guild_post hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | }
| + | |
− | | + | |
− | function char_pre( $data )
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"green\">This is a char_pre hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | | + | |
− | }
| + | |
− | | + | |
− | function char( $data , $memberid )
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"yellow\">This is a char hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | }
| + | |
− | | + | |
− | function char_post( $data )
| + | |
− | {
| + | |
− | global $roster;
| + | |
− | | + | |
− | $this->messages .= "<span class=\"red\">This is a char_post hook</span><br />\n";
| + | |
− | | + | |
− | return true;
| + | |
− | }
| + | |
− | }</php>
| + | |
− | | + | |
− | | + | |
− | ===Variable Calls===
| + | |
− | These are added to index.php for some additional support
| + | |
− | | + | |
− | If you add these into index.php you can turn off the header, footer and menu on the page, by default these are always on.
| + | |
− | <php>$roster->output['show_header'] = false; // Turn off roster header
| + | |
− | $roster->output['show_menu'] = false; // Turn off roster menu
| + | |
− | $roster->output['show_footer'] = false; // Turn off roster footer</php>
| + | |
− | | + | |
− | $roster->output['show_menu'] can accept a string or an array of button listings to display<br>
| + | |
− | When building an addon, you can build your own button listing that only displays on your addon pages<br>
| + | |
− | Pass a string for only one set of buttons, or pass an array for multiple sets of buttons
| + | |
− | <php>$roster->output['show_menu'] = 'main'; // Display the main button listing
| + | |
− | $roster->output['show_menu'] = array('main','char'); // Display the main and char button listing</php>
| + | |
− | | + | |
− | <php>$roster->output['html_head'] = 'string';</php>
| + | |
− | Accepts any string needing to be in the html header for your addon, such as javascript inclusion<br>
| + | |
− | roster_header.tpl will pick this variable up and place its contents in the header
| + | |
− | | + | |
− | <php>$roster->output['body_attr'] = 'string';</php>
| + | |
− | Accepts any string needing to be in the <body> tag in roster_header.tpl
| + | |
− | | + | |
− | <php>$roster->output['body_onload'] = 'string';</php>
| + | |
− | Accepts any string needing to be in <body onload=""> in roster_header.tpl
| + | |
− | | + | |
− | | + | |
− | Any output needed, just print or echo it<br>
| + | |
− | Roster uses php's output buffering to capture all print or echo commands<br>
| + | |
− | Then it echos the output where needed
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ===Variables and Functions for AddOns===
| + | |
− | There are many variables, functions, and classes available for Addons to use
| + | |
− | | + | |
− | | + | |
− | | + | |
− | ====Variables====
| + | |
− | This is a list of variables that are available for your Addons
| + | |
− | | + | |
− | All variables are available whether during update hooks or in the framework
| + | |
− | | + | |
− | * <span style="color:maroon;">$roster</span>->db
| + | |
− | ** Database layer for roster
| + | |
− | * <span style="color:maroon;">$roster</span>->locale->wordings
| + | |
− | ** Every locale array
| + | |
− | * <span style="color:maroon;">$roster</span>->locale->act
| + | |
− | ** The current global locale string array
| + | |
− | * <span style="color:maroon;">$roster</span>->config
| + | |
− | ** The roster configuration array
| + | |
− | * <span style="color:maroon;">$roster</span>->pages
| + | |
− | ** Array of current pages accessed
| + | |
− | * <span style="color:maroon;">$roster</span>->data
| + | |
− | ** Current scope data
| + | |
− | *: For a list of what is in here, see RosterDiag
| + | |
− | * DIR_SEP
| + | |
− | ** OS specific directory separator
| + | |
− | * ROSTER_BASE
| + | |
− | ** Full path to roster directory including DIR_SEP at the end
| + | |
− | * ROSTER_LIB
| + | |
− | ** Full path to roster lib directory including DIR_SEP at the end
| + | |
− | * ROSTER_ADDONS
| + | |
− | ** Full path to roster addons directory including DIR_SEP at the end
| + | |
− | * ROSTER_ADMIN
| + | |
− | ** Full path to roster admin directory including DIR_SEP at the end
| + | |
− | * ROSTER_AJAX
| + | |
− | ** Full path to rosters ajax directory including DIR_SEP at the end
| + | |
− | * ROSTER_LOCALE
| + | |
− | ** Full path to roster localization directory including DIR_SEP at the end
| + | |
− | * ROSTER_VERSION
| + | |
− | ** Current Version of Roster
| + | |
− | * ROSTER_URL
| + | |
− | ** Full valid URL to roster's root directory
| + | |
− | * ROSTER_PATH
| + | |
− | ** URL path to roster's root directory
| + | |
− | * ROSTER_INSTALLED
| + | |
− | ** Constant saying that Roster is installed
| + | |
− | *: (addon.php already detects for this and dies if not found)
| + | |
− | * ROSTER_MAXCHARLEVEL
| + | |
− | *: Maximum level that a character in WoW can achieve
| + | |
− | * ROSTER_MAXSKILLLEVEL
| + | |
− | *: Maximum skill level that a character in WoW can achieve
| + | |
− | * <span style="color:maroon;">$roster</span>->db->prefix
| + | |
− | ** Database table prefix
| + | |
− | * <span style="color:maroon;">$roster</span>->db->table(<span style="color:maroon;">$tablename</span>, <span style="color:maroon;">$addon</span>='')
| + | |
− | ** Returns a table name including the database prefix
| + | |
− | *** This will return 'databaseprefix_tablename'
| + | |
− | ** When $addon is passed, use the basename of the addon
| + | |
− | *** This will return 'databaseprefix_addon_basename_tablename'
| + | |
− | * <span style="color:maroon;">$addon</span>['addon_id']
| + | |
− | ** Addon database id
| + | |
− | * <span style="color:maroon;">$addon</span>['basename']
| + | |
− | ** Addon folder name
| + | |
− | * <span style="color:maroon;">$addon</span>['version']
| + | |
− | ** Addon version
| + | |
− | * <span style="color:maroon;">$addon</span>['active']
| + | |
− | ** 0 - if the Addon is disabled : 1 - if the Addon is enabled
| + | |
− | ** Use addon_active('basename') to check if an addon is enabled
| + | |
− | * <span style="color:maroon;">$addon</span>['fullname']
| + | |
− | ** Addon's full name for display
| + | |
− | * <span style="color:maroon;">$addon</span>['description']
| + | |
− | ** Short description of the addon
| + | |
− | * <span style="color:maroon;">$addon</span>['credits']
| + | |
− | ** Serialized array of credits
| + | |
− | * <span style="color:maroon;">$addon</span>['icon']
| + | |
− | ** Addon's display icon
| + | |
− | * <span style="color:maroon;">$addon</span>['dir']
| + | |
− | ** Full path to the Addon's folder
| + | |
− | * <span style="color:maroon;">$addon</span>['css_file']
| + | |
− | ** Full path to the Addon's style.css file
| + | |
− | * <span style="color:maroon;">$addon</span>['css_url']
| + | |
− | ** URL path to the Addon's css file, this is not the full url path
| + | |
− | * <span style="color:maroon;">$addon</span>['conf_file']
| + | |
− | ** Full path to the Addon's 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]] | + | |