The Turf Data Retrieval System allows generic applications, such as dynamic web pages, to fetch up-to-the-instant public information from Turf in an easy-to-use format. The Turf Data Retrieval System is used by many pages, already, including the Turf homepage, the clans listing page, the leagues listing page, various clan hompages, and this page (introspectively).
This section refers to a language known as PHP - you may pick up the essentials of this language from the section below, however, complete documentation is available in a variety of formats from the PHP documentation page.
Clanlib provides a simple interface for clans to extract dynamic information. To make use of this library create a file ending with .php - if this is to be your clan's main page name it index.php. Add the following to your .php file at the top:
<?php
require( "http://www.turf.org/datasys/clanlib.phps" );
?>
All example fragmets of code below assume that this sequence has appeared
at the top of the file.
The basic unit of data in Clanlib is an array representing your clan. Bits of information can then be easily displayed. For example, this would get the clan information of clan "Newbies" and show their player killing status:
<?php
$newbies = clan_info( "newbies" );
if ( $newbies["pk"] ) {
echo( $newbies["name"] . " is a player killing clan - die!" );
} else {
echo( $newbies["name"] . " is a peaceful clan - group with us." );
}
?>
This example also handles name changes - "Newbies" was the original name,
so we can use it in Clanlib and Clanlib will tell us the current name in
case it was changed.
The clan info array provides the following pieces of information:
"active"
"balance"
"chieftain"
"clanheroes"
"description"
"election"
"election_end"
"financing"
"internal_name"
"joinable"
"joinclose"
"max_clanheroes"
"max_subchiefs"
"mdeaths"
"members"
"mkills"
"motto"
"name"
"overlord"
"pdeaths"
"pk"
"pkills"
"plosses"
"ps"
"pthefts"
"salestax"
"score"
"subchiefs"
"url"
"withdraw_chieftain"
"withdraw_clanhero"
"withdraw_clansman"
"withdraw_subchief"
Clanlib provides the following functions:
This function returns an array containing the clan information shown above for the clan matching "clan name". Note that clan names can change - if you use the original clan name your page will always work.
Example Code
<?php
$omks = clan_info( "omks" );
if ( $omks["overlord"] ) {
echo( "The current OMKS Overlord is " . $omks["overlord"] );
} else {
echo( "We're currently electing our overlord - the voting "
. "ends around " . $omks["election"] );
}
?>
Example Result
The current OMKS Overlord is Mangoor
We're currently electing our overlord - the voting ends around 4.42:13 PM - Fri, 13 April 2001
Set the sorting order to be dependent on "clan attribute" - this may by any attribute in a clan array (as listed above). This function affects clan_target( "clan name" ), clan_anklebiter( "clan name" ), clan_rival( "clan name" ), and clan_rank( "clan name" ).
Example Code
<?php
clan_sortby( "balance" );
$rank = clan_rank( "omks" );
if ( $rank == 1 )
$rd = "st";
elseif ( $rank == 2 )
$rd = "nd";
elseif ( $rank == 3 )
$rd = "rd";
else
$rd = "th";
echo( "OMKS currently ranks " . $rank . $rd . " in clan bank "
. "account balance." );
?>
Example Result
OMKS currently ranks 1st in clan bank account balance.
This function returns the ranking of clan "clan name" compared to all other clans regarding whatever the current sorting attribute is (set by clan_sortby( "clan attribute" ) and defaulting to "score" if clan_sortby( "clan attribute" ) has not been called yet.)
This function returns the ranking above clan "clan name" by one place regarding whatever the current sorting attribute is (set by clan_sortby( "clan attribute" ) and defaulting to "score" if clan_sortby( "clan attribute" ) has not been called yet.) This function may return nothing if no clan is above "clan name" with regards to the sorting attribute (i.e. if your clan is in first place then you don't have a target).
This function returns the ranking below clan "clan name" by one place regarding whatever the current sorting attribute is (set by clan_sortby( "clan attribute" ) and defaulting to "score" if clan_sortby( "clan attribute" ) has not been called yet.) This function may return nothing if no clan is below "clan name" with regards to the sorting attribute (i.e. if your clan is in last place then you don't have an anklebiter).
This function returns the clan with the score closest to clan "clan name" whether ahead or behind by one rank regarding whatever the current sorting attribute is (set by clan_sortby( "clan attribute" ) and defaulting to "score" if clan_sortby( "clan attribute" ) has not been called yet.) This function may return nothing if no clan is above or below "clan name" with regards to the sorting attribute (i.e. if your clan is the only one then you clearly don't have a rival).
This function returns an array of clan members, sorted in rank order. Each element of the array is in turn an array containing:
Example Code
<TABLE border="0">
<TR>
<TD>Name</TD>
<TD>Rank</TD>
<TD>Contribution</TD>
</TR>
<?php
$members = clan_members( "omks" );
for ( $index = 0; $index < count( $members ); ++$index ) {
echo( "<TR>\n" );
echo( "<TD>" . $members[$index]["name"] . "</TD>\n" );
echo( "<TD>" . $members[$index]["rank"] . "</TD>\n" );
echo( "<TD align=\"right\">" . $members[$index]["contribution"] . "</TD>\n" );
echo( "</TR>\n" );
}
?>
</TABLE>
Example Result
Name Rank Contribution Mango overlord 51 Katie chieftain 703
Example Clanlib Use
More example code using Clanlib can seen here.
Turf's Data Retrieval System can be used through PHP with the following PHP library file:
To use the library call
You can view an example of using the library and the resulting PHP data structures and array members for an example commmand using this form:
Example Code Using turfDRS.phps
This (complete) section of code will list the heroes in the Heroes's
League.
<?php
require( "datasys/turfDRS.phps" );
$pos = array( "Zeroth", "First", "Second",
"Third", "Fourth", "Fifth" );
$data = turf_fetch_data( array( "/league/heroes" ) );
?>
<TABLE border="1">
<?php
$hl = $data["/league/heroes"]["records"];
for ( $index = 0; $index < count( $hl ) && $index < 50; ++$index ) {
if ( $index % 10 == 0 ) {
echo( "<TR>\n" );
echo( " <TH colspan=\"4\">" . $pos[$index / 10 + 1] . " Division</TH>\n" );
echo( "</TR>\n" );
}
echo( "<TR>\n" );
echo( " <TD>" . (($index % 10) + 1) . "</TD>\n" );
echo( " <TD>" . $hl[$index]["name"] . "</TD>\n" );
echo( " <TD class=\"digit\">" . number_format( $hl[$index]["score"] ) . "</TD>\n" );
echo( " <TD>" . ereg_replace( " ", " ", date( "h.i:s A - D, d F Y T", $hl[$index]["time"] ) ) . "</TD>\n" );
echo( "</TR>\n" );
}
?>
</TABLE>
More Examples
The following commands are currently available from the Turf Data System:
The Turf data system is built on top of HTTP. The port on which it runs is the port Turf runs on plus 2. Only the GET line of a request will be honoured, and all connections are connection-close style only.
The Turf data system is organised into records - each command will return one or more records, each on a line of its own. Each record is composed of name-value pairs. The exact sequence of return is:
The value half of a name-value pair may be any of four data types - please note that regardless of type all values are followed by a comma: