LOTRoster 1.5.0

Copyright 2011 - Eric Sauvageau - (merlin@lostrealm.ca)
Website: http://www.lostrealm.ca/lotroster

Code based on Roster Master Stand Alone (http://www.lostrealm.ca/rostermaster)
Original code by Rex "SaintPeter" Schrader (rostermaster@bellumaeternus.com)

Additional credits:
Icon artwork: Chivalry (based on Turbine icons)
Original piechart code by Rasmus Petersen (http://www.peters1.dk)
Some Javascript code from Dynamic Drive http://www.dynanicdrive.com.
Part of the forum/CMS interface code based on code from RaidNinja by Nate Bundy and Derek Lee.


1.About

1.1 Introduction
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.

1.2 Features


2. Installation

2.1 Requirements

2.2 Optional

2.3 New Install

  1. Unzip the installation files to a local computer
  2. (Optional) Rename includes/config.php.dist to includes/config.php and edit it if you do not wish to or cannot use the supplied web interface to do so later.
  3. Upload the lotroster directory to your website (through FTP or other mean)
  4. Set permissions on includes and includes/config.php to 770 (Allow user and group to write) and set owner to the user running the web server (usually apache or nobody). Example: chown apache includes/config.php
    chown apache includes chmod 770 includes

    chmod 770 includes/config.php OR:
    Set includes and includes/config.php to 777 (Allow all to write - less secure, but some virtual hosts won't let you set ownership to the user running the web server)
    OR:
    Leave it as is, and when saving configuration through the web interface you can manually copy and paste the generated config into the config.php file.
  5. (Non-SQL users): Set permissions on the lotroster directory and logfile.html file to 777 (allow all to write)
  6. (SQL users): If you don't already have a database, create a new one. Refer to your server admin if you don't know how, the procedure varies between servers.
  7. Enter the configuration interface using http://yoursite/lotroster/rmadmin.php
  8. If prompted to, enter a new admin password.
  9. Verify your PHP settings, by clicking on "Verify PHP Features".
  10. Configure LOTRoster by clicking on "Edit Configuration".
  11. (SQL users) Select "Initialize Database" to create all required tables.
  12. Force a refresh of the roster, by clicking on "Force Refresh".
  13. If using offline update (highly recommended) then please jump the the Scheduled (offline) roster updating section of this documentation.

2.4 Upgrading from an older version

  1. Unzip the installation files to a local computer.
  2. Make a backup of your existing lotroster directory on your site, especially the CSS files if you customized them.
  3. Upload the lotroster directory in place of the old one except for the logfile.html file if it already exists and you want to keep it. Your existing configuration will not be overwritten.
  4. Restore any customized CSS (if any). Take note of any mention regarding CSS changes when reviewing the release notes, and adjust any customized CSS accordingly.
  5. Enter the Configuration section of LOTRoster, and select "Edit Configuration" to configure any new settings, then save it.
  6. (SQL Users) Select the appropriate Upgrade option from the Configuration section, if any.
  7. If you overwrote logfile.html and are not using a database, change its permission back to 777 (Allow all to write)
  8. Force a refresh of the roster, by clicking on "Force Refresh".

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:

  1. Enter the Configuration section, and Edit Configuration to enter a new database prefix.
  2. After saving the new configuration, select the Alter Table Name option to upgrade your prefix-less tables names.

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:

/path_to_php/php /path_to_webcontent/path_to_lotroster/update.php

For example, for hostings using cPanel this will look like this::

/usr/local/bin/php /home/hostlogin/public_html/lotroster/update.php

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. Configuration


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.


3.2 Authentication


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.


3.3 Icons


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 only".

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.


3.4 Template

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.


Char Claiming:
avatar
username
type

Basic fields:
name
rank
rankname (combined)
class
classlevel (combined)
level
race
*origin
vocation
pvmprating
pvmppoints
pvmprank
profname1
profname2
profname3
dkp


Custom Fields

custom1
custom2
custom3
custom4
custom5


Extra stats:
*morale
*power
*armour
*might
*agility
*vitality
*will
*fate
*finesse
*criticalAvoid
*criticalHit
*commonDef
*block
*evade
*parry



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

4.1 About

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 Master.

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

5.1 index.php

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.

5.2 logfile.html

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 single line:

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.


License
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 and/or
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.