Copyright 2011 - Eric Sauvageau -
Code based on Roster Master Stand Alone (http://www.lostrealm.ca/rostermaster)
Original code by Rex "SaintPeter" Schrader (email@example.com)
Icon artwork: Chivalry (based on Turbine icons)
Original piechart code by Rasmus Petersen (http://www.peters1.dk)
Part of the forum/CMS interface code based on code from RaidNinja by Nate Bundy and Derek Lee.
LOTRoster is a web application written in PHP that allows you to display your Lord of the Ring Online guild roster on your personal guild website. Information is automatically fetched from Turbine's data.lotro.com XML feeds, and is kept in a local cache for performance.
LOTRoster is a port of RosterMaster Stand Alone (from the same author), a similar application but aimed at Sony's Everquest II game. Its ancestor, Roster Master, was originally written by Rex "SaintPeter" Schrader.
Please consult the included docs/CHANGELOG.txt file for details about what was changed between versions. Some important information about upgrading can be found there.
2.3 New Install
2.4 Upgrading from an older version
2.5 Adding a prefix to an existing table
You can insert a prefix at the start of the LOTRoster database tables. This is handy if you wish to have multiple installations of LOTRoster inside the same database. To insert a prefix to an already configured installation:
2.6 Scheduled (offline) roster updating
While LOTRoster can be configured to automatically update itself as needed when people view the roster, this can lead to numerous issues if you decide to also poll extra character data from Turbine's website. The recommended method is to configure a scheduled task (also called a “Cron job” in the UNIX/Linux/BSD world) to regularly (once every 24 hours is the recommended interval) poll Turbine's data.lotro.com site to retrieve the latest roster information, and store it locally in your database.
First, make sure your web host allows you to configure your own scheduled tasks or cron jobs. If in doubt, contact your technical support for assistance. You will also need to know the full path to the "php" executable (usually /usr/local/bin/php or /usr/bin/php), and the full path to your web content (you can find it by going to the Verify PHP Features section of LOTRoster's configuration interface).
With these information in hand, create a cron job that will look something like this:
For example, for hostings using cPanel this will look like this::
First, set it to run in the next few minutes, then monitor LOTRoster's log. If you see "Updated local cached data" then it's working. Change the cron job frequency to something reasonable (every 24 hours is recommended - using a lower value will NOT result in more frequent updates and might get you banned by Turbine from their data feeds - their feeds only update themselves every 24 hours anyway).
If you are using a Windows-based host, you can create the Scheduled
Task from a command prompt. Open a command prompt (with elevated privileges if you are
under Windows Vista/7/2008 Server), and create the task with this command:
schtasks /create /tn "LOTRoster Data Refresh" /tr "F:\path\to\php.exe F:\path\to\lotroster\update.php" /sc daily /st HH:MM
Enter the correct paths to php.exe and update.php, and also replace HH:MM with the time at which you wish to have the task run (just like with a cron job, it's recommended to use an odd hour in the middle of the night, like 02:42).
3.1 Configuration through the web interface
LOTRoster can be entirely configured through a web interface. However, if you are unable to do so, you can use the included config.php.dist file. Edit it, then save it as includes/config.php. It is however better to use the supplied web interface, to avoid any mistake that would prevent LOTRoster from running.
Access to the Configuration interface is password-protected. The first time you enter it, you will be asked to change the default password to a new one. This password will allow you to log in LOTRoster with administrative privileges, which will allow you to access the Configuration interface, manage character claims without restriction, or view the complete log (some log entries are hidden from regular users, such as those containing SQL queries). The password can be changed at a later time through the Configuration interface, by clicking on Edit Configuration.
It is possible to (optionally) display icons in some of the columns (such as rank, class, vocation, etc...). Through the Configuration interface you will be able to configure which icons to display, their size, and file extensions. LOTRoster comes bundled with a complete iconset prepared by Chivalry based on Turbine's own icons.
Each field that supports icons can be set to display either as
"Text only", "Icon + Text", or "Icon
You can specify a size of '0' if icons of a given category aren't all of the same size - they will then be displayed at whatever size they originally are.
You can select which columns to display and in what order by defining your display templates. Here's a list of available fields. The "combined" fields are fields containing two different information in one single column.* = fields only available when enabling Extra Character Data.
3.5 Displaying DKP data
LOTRoster can import DKP data from one of the supported applications (currently supported: EQDKP and EQDKP-Plus). You will then be able to display everyone's DKP balance on your roster by inserting the 'dkp' field in your display template. You will need to provide the database address, name, username and password in LOTRoster's configuration.
Afterward, LOTRoster will automatically pull up-to-date data from
the selected DKP application at the same time it will poll data from
data.lotro.com. You can also manually force a refresh of the DKP
data through LOTRoster's configuration interface.
3.6 Custom Fields
LOTRoster lets you define up to 5 custom fields to display on your roster. Each field can be named as you wish, and each one can also be defined as user-editable (provided you are integrating with a supported portal/forum software), or admin-only editable. Such fields can be used to keep track of loot, questlines, attendance, etc...
Administrators can also enter clickable links and even inline images in those fields. To do so, enter the data using this syntax:
link(url,text) - Create a clickable link pointing to 'url', displayed as 'text' in the field
img(url) - Display an inline image in the field.
Note: you cannot mix link() or img() with anything else - it must be the only thing currently entered in that field.
4. Character Mapping
Character mapping allows you and your users to user claim their in-game characters against their forum or portal user name. Regular users who are logged in will have the option to claim and unclaim characters. If you are logged as an administrator in LOTRoster you will also be able to manage claims, be it deleting existing claims or creating new claims for any user.
4.2 Forum Requirement
In order to use the character mapping feature, you must have one of the supported forum or portal softwares installed and configured. Those currently supported are:
Other versions of these may or may not work, as they haven't been tested.
You must use the same database to store both your forum/portal tables as well as your lotroster tables. Also, see the note below concerning cookies..
Note that Drupal, SMF and vBulletin require an additional setting in LOTRoster's configuration. In both cases you must specify the relative path to their respective configuration file. Assuming that the lotroster folder is located inside your forum's folder, the SMF setting will look like "../Settings.php", while in vBulletin's case this would be "../includes/config.php". Drupal 6.x is usually "../sites/default/settings.php". All other portal/forum software don't need this extra parameter.
4.3 How authentication is handled
The character mapping uses the session id cookie from a valid
login to the configured forum to validate the user. Each time a
LOTRoster page is loaded, the cookie is fetched and looked up in the
database. This means that you must have logged into the forums before
you may access the member specific features of Roster
Important note about Cookies:
Your LOTRoster install must be in the cookie "Path" for the forum software. For some software (like phpBB) this will default to "/", so it's not a problem. Others however might have a cookie path of, for example, /forum/ . In that case, you must install LOTRoster inside that folder, so it can share the same cookie path (in that example, under /forum/lotroster/).
5. Website Integration
LOTRoster comes with a sample index.php. This file will
work fine "out of the box". Drop a link to it off your
front page. Two basic visual styles (css files) are provided:
lotroster1.css (dark-themed) and lotroster2.css (light-themed).You
can select which one to use by editing the index.php file, or by
directly editing these CSS files.
You can easily integrate LOTRoster by dropping the following code into an arbitrary .php file:
<? include("lotroster/lotroster.php"); ?>
This will insert a complete LOTROster table. Note that you may need to adjust the path to the lotroster.php file if you are including from another folder. You will also need to include LOTRoster's CSS.
Make sure to update your configuration to reflect the filename of the page calling lotroster.php, as well as the relative path of that file.
When not using a database for storage, the file logfile.html is used to hold the log data. You may modify the log file extensively, so long as you retain the HTML comment <!-- Insert Log Here -->. The log update will be placed at the location of that HTML comment.
NOTE:If you are using an SQL database, then the logging will be done in an SQL table. In that case, you can delete the logfile.html file.
5.3 Incorrect display of accents
If accents aren't properly showing up in character names then your
web server might not be configured to display UTF-8. You can get
around this by creating a file named '.htaccess', with this
php_value default_charset UTF-8
Then save it in the folder where you have your index.php file. This will instruct your web server (and PHP) to output data in UTF-8, for proper display of accented characters.
Also, if using an SQL database, make sure your database is configured to handle UTF-8.
Copyright 2007-2011 Eric Sauvageau
Original code based on Roster Master by Rex "SaintPeter" Schrader, Copyright 2005.
Some code contributed by various members of the Everquest II community.
This program is free software; you can redistribute it
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.