HTML Templates
--------------
An HTML template is an HTML file with embedded Fragstats tags. Fragstats substitutes
values for the embedded tags. This is much more powerful than simple headers and
footers and has been the most requested new feature of Fragstats.

This feature should make it possible to merge Fragstats output seamlessly into your
web pages, remove features you don't want and add ones you do.

The first thing to do is to have a look at the fragstats.cfg, maintemp.html,
top20temp.html and cgitemp.html files for examples of templates in action. I
deliberately designed these templates to generate output almost identical to the
default Fragstats output. Of course, you can change these or write your own. It's
up to you to decide what you want to do.

If you decide it's all too complicated, just leave all the templates and htmlout
commands out. Fragstats & Qplayer will happily generate output as they always have.

Lastly, a special request. Templates gives you complete control over how the output
looks. I've included the special tag <?fragstats> which makes it easy to put a credit
signature, however small, in your pages. Please use it or something similar somewhere
in your page so people know who wrote the program that's generating your stats. Thanks!

User Defined Tags (UDT's)
=========================
User defined tags are a way of allowing you to insert user defined data into the output
generated by Fragstats and Qplayer.

You use the deftag command to define a tag. The format is:

deftag <tagname> as [string|score|file|weapon|expression] <value>

	<tagname> is your name for the tag, minus the <?..> or <!--..-->.
	'string'  specifies <value> is a static string, up to 255 characters in length
		  to be substituted.
	'file'    specifies <value> is a filename (with path) containing data to be
		  substituted.
	'score'   specifies <value> is a special bonus score, eg. Flag Capture. This
		  option will only be useful with GS style logs.
	'weapon'  specifies <value> is a weapon, eg. Railgun. This option will only
		  be useful with GS style logs.
	'expression'
                  specifies <value> is an expression up to 255 characters in length,
                  eg. "10 * 2 / 3". See below for more details.

For example:
	deftag flag_capture as score "F Capture"

Once defined, the tag can be used just like any other tag (see below).

The 'string' and 'file' options can be used to include an often repeated piece of HTML
or text into your Fragstats/Qplayer output. This is especially useful if you have lots
of templates.

A great advantage of this tag system is that you can get Fragstats to record and display
special scores & weapon stats for *any* mod that supports the GS log standard.  If you're
not sure what is being recorded by Fragstats, have a look at the console output it
generates - Any special bonuses & weapons that are found in the logs will be shown there.
I've designed it so you should be able to cut & paste the suggested UDT's directly from
the console output into your config file. It's up to you to then use the UDT's in your
templates. Have a look at the sample templates to see how I've used the <!--html_url-->
UDT.

Expressions
===========
Expression support in UDT's has been added in 1.08. This powerful feature lets you
design your own stats built from existing stats in the database. Existing stats are
references by their tag name minus the <!-- --> or <? >, eg. <!--skill--> is
referenced as skill.

The scope of the expression is to that player. This means that using the skill
tag in an expression returns the skill value of that player being currently processed.
You can't reference other players stats to do comparison type calculations.

Features:
. Full expressions
. Multiple levels of parenthesis
. Use any existing tag in your expressions
. Use any special score, weapon or even user defined expression in your expressions
. Sort by expression fully supported for HTML output, just specify your expression
  UDT as the sort parameter of the 'htmlout' option.

Grammer:
   expression = expression operator expression
                || ( expression )
                || function
                || number
                || tag

   function   = identifier ( expression )

   number     = integer
                || floating-point

   tag        = builtin-tag
                || user-defined-tag

The following operators are supported:

   *   multiplies
   /   divides
   +   adds
   -   subtracts
   %   modulo

The following functions are supported (at the moment):

   abs(X)     returns the absolute value of X
   round(X)   rounds X to the nearest integer
   int(X)     returns the integer value of X
   sin(X)     returns the sine of X (radians)
   cos(X)     returns the cosine of X (radians)
   tan(X)     returns the tangent of X (radians)
   asin(X)    returns the arcsine of X
   acos(X)    returns the arccosine of X
   atan(X)    returns the arctangent of X
   log(X)     returns the natural logarithm of X
   exp(X)     returns the exponential value of X   

Examples:

   deftag myskill as expression "round(skill / (efficiency + 1))"

   deftag skillmod as expression "myskill % 10"

   deftag rocketskill as expression "rocket_launcher * skillmod"

Any expressions you define are accessed just like any other UDT, so to output the
value of 'skillmod' above, just use <!--skillmod-->

Notes:
1. Tags that do not have a numeric equivalent will generate an error message, but
   still process with a value of zero. Some tags have a non-simple numeric output,
   such as 'duel' (win/loss) and the weapon stats (kills/deaths). These tags will
   return a single value, win - loss for duel and kills - deaths for weapons.

2. Use of an invalid or illegal tag will generate an error, but still process with
   a value of zero.

2. Expressions are limited to 255 characters in length. You can get around this by
   defining multiple expression UDT's that get grouped together as the examples above
   show.

3. You can define expressions that call sub expression UDT's, but make sure you don't
   create an infinite loop when the expression is used. You will quickly use all the
   resources in the machine, and Fragstats/Qplayer will crash. An example of what not
   to do:

   deftag infinite_loop as expression "infinite_loop"

4. Expression values are returned as a floating point number, rounded to 2 decimal
   places.

5. Sorting by expressions can be slow, especially when the expression is complicated
   or you have a large number of players in the database.

The htmlout command
===================
HTML templates are specified for use by the htmlout command. The format of this is:

htmlout [<num>|all] by [reverse] <sort> using <template> [output|append] <file>

	<num> is any number up to the number of players. If you want all players output,
           specify "all".
	"reverse" signifies you want the sort order to be reversed, eg. you get the lowest
	   scores first.
	<sort> is Rank,Frags,Deaths,Skill,Efficiency,Suicides,Duel,Connect Time,
	   Maps Played,FPH,Ping,Last Seen or any special score, weapon or expression
           defined by a UDT.
	<template> is the HTML template file name. You can also specify "complete" or
	   "top20" indicating use of the two internal default templates.
	"output" signifies open and initialise, "append" means open for appending. You
	  can use appending to put mulitple sorts into the same file, eg. if you wanted
          a single HTML file with the top player by Frags, Rank and Skill.
	<file> is the target file name.

For example:

	htmlout all by frags using maintemp.html output Frags.html

Directs Fragstats to output all players sorted by frags using the template file
maintemp.html and send the resultant output to the file Frags.html. There is no limit to
the number of htmlout commands or templates you can define.

The sort order is fairly obvious except for duel. When sorting by duel, results are ordered
the ratio of wins to losses. An additional option 'duelthresh' has been provided which
allows you to specify a Duel Threshold. Specifying this will cause players with fewer Wins
to sort lower than players who exceed the threshold value.

Htmlout can be used in the config file or on the command line.

The template file
=================
Tags are denoted by the <?tag> sequence or the <!--tag--> sequence. You can use either
format interchangably. Examples below are using the <?tag> format.

Tags that can be embedded into an HTML template are:

<?date>			Date & time the page was generated
<?effthresh>		Efficiency threshold - players with fewer frags than this get
			   an efficiency of 0%
<?duelthresh>		Duel sort threshold - players with fewer frags than this get
			   sorted lower
<?server>		Server name
<?sort>			Sort type
<?fragstats>		Fragstats signature
<?totplayers>		Total number of players in the database
<?totfrags>		Total number of frags in the database

<?embed_players>	Special tag that signifies player output. After this tag you
			   can also specify:
	<?position>		Players ranking (by that sort)
	<?position_pad>		Players ranking (by that sort) padded to 32 chars
	<?playername>		Players name
	<?playername_pad>	Players name padded to 8 chars
	<?frags>		Players frags
	<?frags_pad>		Players frags padded to 8 chars
	<?deaths>		Players deaths
	<?deaths_pad>		Players deaths padded to 8 chars
	<?suicides>		Players suicides
	<?suicides_pad>		Players suicides padded to 8 chars
	<?rank>			Players rank
	<?rank_pad>		Players rank padded to 8 chars
	<?efficiency>		Players efficiency
	<?efficiency_pad>	Players efficiency padded to 10 chars
	<?skill>		Players skill
	<?skill_pad>		Players skill padded to 8 chars
	<?duel>			Players duel wins/losses
	<?duel_pad>		Players duel wins/losses padded to 10 chars

<?end_embed>		Special tag that signifies end of player output.

* New 1.07/1.07a tags *

NOTE: Many of these tags are only useful when using GS style logs. Quake World
frag logs *do not* contain the team, map and weapon entries required to generate these
stats. If you are processing QW frag logs, you will only get the 'Overall Stats'
statistics and no weapon or team based statistics.

	<?connect_time>		Displays the total connect time for that player
	<?maps_played>		Displays the number of maps *completed* by that player
	<?last_seen>		When that player was last seen on the server
	<?ping>			Average ping of a player
	<?fph>			Frags per Hour of a player
	<?fphthresh>		FPH threshold - players with less connect time than
				   this get sorted lower

* New 1.06 tags *

NOTE: Many of these tags are only useful when using GS style logs. Quake World
frag logs *do not* contain the team, map and weapon entries required to generate these
stats. If you are processing QW frag logs, you will only get the 'Overall Stats'
statistics and no weapon or team based statistics.

<?embed_maps>		Special tag that signifies multiple map output. After this tag
			   you can also specify:
	<?map_name>		Displays the map name
	<?map_path>		Names the subdirectory where that maps stats are kept

<?embed_teams>		Special tag that signifies multiple team output. After this tag
			   you can also specify:
	<?team_name>		Displays the team name
	<?team_name_pad>	Displays the team name padded to 32 chars
	<?total_team_score>	Total score for that team
	<?total_team_score_pad>	Total score for that team padded to 8 chars

Use <?end_embed> to signify the end of a map list.

NOTE:
The map_name, map_path and team tags can be specified outside the embed/end_embed, in
the same way as the player stats can be. In this case they represent the current map
or path, or the current player's team info.

<?map_numplayers>	Shows the number of players for the current map. For
			   the special map 'Overall Stats', this is the same
			   as <?totplayers>.
<?map_numfrags>		Shows the number of fragsfor the current map. For
			   the special map 'Overall Stats', this is the same
			   as <?totfrags>.
<?page_name>		Shows the name of the current output filename as specified
			   in the 'htmlout' command.

When a <?embed_players> tag is encountered, this tells Fragstats to substitute a
specified number of players. The number of players is specified via the htmlout command.

When an <?embed_maps> tag is encountered, this tells Fragstats to substitute the list
of maps in the database. If you are using QW frag logs or you have suppressed map
statistics ('disablemapstats' option), you will only see 'Overall Stats' when you
output the map list.

When an <?embed_teams> tag is encountered, this tells Fragstats to substitute the list
of teams in the database.

A special HTML template can be specified for the CGI program Qplayer via the cgitemplate
command. There is no equivalent command to 'htmlout' for Qplayer, rather you specify the
location of the CGI template file via the 'cgitemplate' command. Qplayer will use this
file as a template when it is run by the end user.

Because the scope of Qplayer's operation is at the individual level, there are
some differences between the tags available to Fragstats and Qplayer. The tags available
to Qplayer are:

<?date>			Date & time the database was generated
<?effthresh>		Efficiency threshold - players with fewer frags than this get
			   an efficiency of 0%
<?server>		Server name
<?fragstats>		Fragstats signature
<?totplayers>		Total number of players in the database
<?totfrags>		Total number of frags in the database
<?playername>		Players name
<?playername_pad>	Players name padded to 32 chars
<?frags>		Players frags
<?frags_pad>		Players frags padded to 8 chars
<?deaths>		Players deaths
<?deaths_pad>		Players deaths padded to 8 chars
<?suicides>		Players suicides
<?suicides_pad>		Players suicides padded to 8 chars
<?rank>			Players rank
<?rank_pad>		Players rank padded to 8 chars
<?efficiency>		Players efficiency
<?efficiency_pad>	Players efficiency padded to 10 chars
<?skill>		Players skill
<?skill_pad>		Players skill padded to 8 chars
<?duel>			Players duel wins/losses
<?duel_pad>		Players duel wins/losses padded to 10 chars
<?team_name>		Players team name
<?total_team_score>	Total score for Players team

<?embed_victims>	Special tag that signifies victim output
<?embed_deaths>		Special tag that signifies deaths output. After these tags you
			   can also specify:
	<?victimname>		Victim's name.
	<?victimname_pad>	Victim's name padded to 32 chars
	<?bodycount>		Number of times they were killed
	<?bodycount_pad>	Number of times they were killed padded to 8 chars
<?end_embed>		Special tag that signifies end of player output

<?embed_maps>		Special tag that signifies multiple map output. After this tag you
			   can also specify:
	<?map_name>		Displays the map name
	<?map_path>		Names the subdirectory where that maps stats are kept
	<?map_name_url>		Generates a link to Qplayer for that player on that map

<?embed_weaps>		Special tag that signifies multiple weapon output. After this tag
			   can also specify:
	<!--weap_name-->        weapon name
	<!--weap_kills-->       kills by that weapon
	<!--weap_deaths-->      deaths by that weapon


Use <?end_embed> to signify the end of a map list or weapons list. Both map_name and
map_name_url can be specified outside the embed/end_embed. In this case they represent
the current map and link to the current page. The weap_name, weap_kills and weap_deaths
tags can also be specified outside the <?embed_weaps>, but you'll just get stats for
the first weapon that player has stats for.


'Embed' tags
============
Mostly, tags are substituted 1 for 1 when the template is processed. When an 'embed'
is encountered, that directs Fragstats (or Qplayer) to use the HTML up to the next
'end_embed' tag to substitute a list of data. If embedding players, Fragstats will loop through the number of
players specified in the 'htmlout' command, while Qplayer will loop through the complete
victim or death lists for that player. For example, to make a table with player stats in
it:

<table>
<?embed_players>
<tr>
<td><b><?position></b></td>
<td align=left><b><?playername></b></td>
<td><?frags></td>
<td><?deaths></td>
<td><?suicides></td>
<td><?rank></td>
<td><?efficiency>%</td>
<td><?skill></td>
</tr>
<?end_embed>
</table>

When Fragstats processes the template containing this code, it finds the <?embed_players>
tag, then starts outputing the player database using the HTML and tags up to the
<?end_embed> tag. You specify the number of players to output via the 'htmlout' command
(see above). Qplayer operates in a similar fashion. Have a look at the cgitemp.html file
for an example of how to specify a template for Qplayer.
