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)
=========================
With 1.06, you can now define your own tags. The feature is limited for now, in that
only special bonus scores, static strings and files can be substituted, but I may
enhance the feature in the future to allow for expressions.

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

deftag <tagname> as [string|score|file] <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.

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.

The great advantage of this tag system is that you can get Fragstats to record and display
special scores for *any* mod that supports the GS log standard.  If you're not sure what
bonuses are being recorded by Fragstats, have a look at the console output it generates.
Any special bonuses 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.

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

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

	<num> is any number up to the number of players. If you want all players output,
           specify "all".
	<sort> is one of rank,frags,deaths,skill,efficiency,suicides or duel.
	<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

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 has been provided with 1.06 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.

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.

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%
<?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.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.
