   ____ _   _    _  _____    _        _
  / ___| | | |  / \|_   _|__| |_ __ _| |_ ___
 | |   | |_| | / _ \ | |/ __| __/ _` | __/ __|
 | |___|  _  |/ ___ \| |\__ \ || (_| | |_\__ \
  \____|_| |_/_/   \_\_||___/\__\__,_|\__|___/
              3.1.2 by Baerchen, February 2002
                  for eggdrop 1.4.5+ & TCL 8.3
                     baerchen@germany-chat.net
       latest versions @ home.dal.net/baerchen

HTML TEMPLATES
*********************************************************************

WTH?
---------------------------------------------------------------------
In earlier versions of CHATstats, you've had to go with my crappy
in-script HTML. This has changed with 3.0.0 and HTML code went to 
external files (the templates). The script parses these files line by
line, looks for placeholders, replaces them with the appropriate
values and writes the whole stuff to a new file.

STILL, WHAT'S THE POINT?
---------------------------------------------------------------------

- Almost full control about the design of the generated pages.
- Include only information you think is worth.
- Put the whole stuff on 20 webpages or just one.

Although this seems to be more complicated than to go with predefined
in-script HTML, it gives all users the opportunity to freely adapt
CHATstats' output to their liking and therefore a high degree of
integration.

GETTING STARTED
---------------------------------------------------------------------
My proposal is to first install the supplied templates, look what
it all can look like and then make your own ones. Open Frontpage,
notepad.exe or whatever and make an html that looks the way you want
it. Now, this new template is subject to a special name convention:

NAMING A TEMPLATE
---------------------------------------------------------------------
All templates have to be named like this:

blabla.global|channelname.template
                          ^--- Never change this part. Must be
                               "template".
       ^--- This part decides whether the template is used globally
            for all channels or for just one channel.
^--- Whatever you want, e.g. 'toptalkers.', to indicate this is
     the toptalkers template. This part will also go into the final
     file.
                 
The script looks for all files in $cs(workdir) with the suffix
'.global.template' and uses them for _all_ channels.

If there's a channel that needs a different template, copy the
template and replace "global" by the exact channelname (no #).
CHATstats will then use this template solely for that channel.

There's no need to rehash or restart - just do '.update'. Also,
you can add and delete templates from the directoy as you like -
CHATstats uses what it finds and will only complain if it finds
no templates at all.

Example:

You have three channels #foo #bar and #foobar

1. There's only the file toptalkers.global.template:
   This is used for all three channels #foo, #bar & #foobar
2. Now you add the file toptalkers.foo.template to the directory:
   This file is used only for channel #foo. #bar and #foobar will
   still use toptalkers.global.template
3. Now you delete the file toptalkers.global.template:
   The only webpage generated will be the one for #foo, since there
   will be no templates found for #bar and #foobar.

This done, we need to insert some stuff into the HTML, so CHATstats
knows where to put what:

INSERTING PLACEHOLDERS AND VARIABLES
---------------------------------------------------------------------

For many information, we just have to insert a PLACEHOLDER into the
HTML code - like %%CHANNEL would always and everywhere be replaced by
the channelname e.g. #foo. Easy.
Listings like TopTalkers a.o. work different. CHATstats uses listings
primarily for 'rank-able' information, e.g. the TopTalkers. In
opposite to placeholders, we just can't insert

 rank1 toptalker1 wordcount1 percent1
 rank2 toptalker2 wordcount2 percent2
 rank3 toptalker3 wordcount3 percent3

in the HTML. This would work for three TopTalkers, but not for four.
Instead we would type

 rank toptalker wordcount percent

and repeat this incl. the HTML code until our listing is complete.
The result is a perfect table showing all Toptalkers from rank 1 to
rank x, where you can define x for yourself. Rank, toptalker,
wordcount etc. is what I call VARIABLES.

Let's get into this. First, we need to tell CHATstats when a listing
starts and ends. We do this by inserting an HTML comment and the type
of listing within the comment:

<!-- type-of-listing x,y -->

x and y are parameters discussed later
Then comes the HTML stuff and the required variables
Last we define the end of the listing by:

<!-- end of type-of-listing -->

These two comments need to be on a line by itself. Never ever add 
other stuff or the template will not be parsed correctly. Also,
leaving out the "end of" comment will completely mess up the
resulting html. For the comments, stick to the exact wording:

AVAILABLE LISTINGS
------------------

LISTING                      RETURNS
<!-- Botnetmap 0,0 -->       A map of the botnet according to
                             '.bottree'. Should be embraced by <pre>
                             tags for proper display
<!-- Partyline 0,0 -->       A list of all current partyline users,
                             sorted alphabetically by nick
<!-- ChanUsers 0,0 -->       A list of all current channel users,
                             sorted in mIRC style
<!-- Bans 0,0 -->            A list of all channel bans  
<!-- Activity x,0 -->        A graph of all spoken words since the
                             script was started, broken down into
                             hourly intervals
<!-- TopJoiners x,y -->      A ranking of users who joined the chan
                             most often
<!-- TopVisitors x,y -->     A ranking of users who stayed in the
                             channel longest
<!-- TopIdlers x,y -->       A ranking of users who are most idle
<!-- TopActiveUsers x,y -->  A ranking of users who are most active
                             basically, this is the difference of
                             TopVisitors and TopIdlers
<!-- TopTalkers x,y -->      A ranking of users who have spoken the
                             most words in the current cycle
<!-- TopAllStars x,y -->     A ranking of users who have spoken the
                             most words since the script was started
<!-- TopKickers x,y -->      A ranking of users who kick most
<!-- TopBanners x,y -->      A ranking of users who ban most
<!-- TopKicked x,y -->       A ranking of users who have been kicked
<!-- TopBanned x,y -->       A ranking of users who have been banned

x = In order not to mess up the webpage, the script needs to know how
    long the drawn bar can be at maximum for Rank 1 of the listing.
    200 is a nice value to start with.
y = the amount of enumerations. There are e.g. 345 TopTalkers, but
    listing them all might not be very informative, so this value
    tells the script where to stop (e.g. 10).

OK, we now know how to include listings in the HTML, what about the 
contents? Next is a list of which variables can be included in what
listing:
    
AVAILABLE VARIABLES WITHIN LISTINGS
-----------------------------------
VARIABLE      RETURNS .. 

<!-- Botnetmap 0,0 -->
No variables available.
<!-- end of Botnetmap -->

<!-- Partyline 0,0 -->
!!USER        one of the partyline users according to 'whom *'
!!BOT         the bot !!USER is on
!!CHAN        the botchannel !!USER is on
<!-- end of Partyline -->

<!-- ChanUsers 0,0 -->
!!USER        one of the channel users according to /names
!!FLAGS       user's botflags for the channel
!!HOST        !!USER's ident@host
!!DUR         !!USER's online time
!!IDLE        !!USER's idle time
<!-- end of ChanUsers -->

<!-- Bans 0,0 -->
!!BAN         one ban from the channel's banlist. You can use this
              more than once e.g. to put two bans in one row/line
<!-- end of Bans -->

<!-- Activity x,0 -->
!!TIME1       time start range e.g. 00:00
!!TIME2       time end range, e.g. 01:00
!!VALUE	      words spoken in time range
!!PERCENT     !!VALUE's percentage in relation to total
!!WIDTH       the current width of the bar
x is the maximum width of the bar in pixels, e.g. 250 pixels
<!-- end of Activity -->

All listings starting with "Top"
e.g. <!-- TopTalkers x,y -->
!!USER        user's nick (e.g. from TopTalkers)
!!RANK        !!USER's ranking
!!VALUE       !!USER's count (joins, words, etc.)
!!PERCENT     !!VALUE's percentual share
!!WIDTH       the current width of the bar
x is the maximum width of the bar in pixels, e.g. 250 pixels
y is the maximum of returned results, e.g. 10 for 10 TopTalkers
e.g. <!-- end of TopTalkers x,y -->

Phew. That was the difficult part. Here's the easy one: placeholders
that return one single value all the time. Include them
where you want and how often you want.

AVAILABLE PLACEHODERS
---------------------

Placeholder          returns ..

%%TOPTALKERSAMOUNT   amount of all TopTalkers (integer)
%%TOPTALKERSWORDS    total wordcount of TopTalkers  (integer)
%%TOPTALKERSLINES    total linecount of TopTalkers (integer)
%%TOPTALKERSRATIO    TopTalkers' words/line ratio (decimal)
%%ALLSTARSAMOUNT     amount of all AllStars (integer)
%%ALLSTARSWORDS      total wordcount of AllStars (integer)
%%ALLSTARSLINES      total linecount of TopTalkers (integer)
%%ALLSTARSRATIO      AllStars' words/line ratio (decimal)

%%TOTALWORDS         Toptalkers' + AllStar's words (integer)
%%TOTALLINES         Toptalkers' + AllStar's words (integer)
%%TOTALRATIO         Toptalkers' + AllStar's words/line ratio (decimal)
%%TOTALJOINS         amount of joins by all users (integer)
%%TOTALKICKS         amount of all kicks the bot has seen (integer)
%%TOTALBANS          amount of all bans the bot has seen (integer)
%%TOTALONLINE        added online time of all users (duration)
%%TOTALIDLE          added idletime of all users (duration)
%%TOTALACTIVE        added active chatting time of all users (duration)

%%CHANNEL            channel name (string)
%%CHANMODES          channel modes (string)
%%CHANTOPIC          channel topic (string)
%%CHANTOPSETTER      nick who set the topic and date (string)
%%CHANUSERS          channel's total user amount (integer)
%%CHANOPS            channel's ops (integer)
%%CHANVOICES         channel's voices (integer)
%%CHANOTHERS         channel's other users (integer)
%%CHAN%USERS         channel's total users percentual share (integer)
%%CHAN%OPS           channel's ops percentual share (integer)
%%CHAN%VOICES        channel's voices percentual share (integer)
%%CHAN%OTHERS        channel's other users percentual share (integer)
%%CHANPEAKVALUE      amount of users channel peaked at (integer)
%%CHANPEAKDATE       date of %%CHANPEAKVALUE (string)

%%TIMEBALANCE        time balance according to $cs(timebalance) (integer)
%%TIMENOW            current day of week, date and time (string)
%%TIMENEXTUPDATE     time of next update (string)

%%SCRIPTSTATUS       "yes" or "no" for CHATstats en- or disabled (string)
%%SCRIPTSTARTED      date of CHATstats' very first start (string)
%%SCRIPTSTOPPED      date when CHATstats was last stopped (string)
%%SCRIPTCYCLE        date of the last cycle (string)

%%BOTNICK            botnick (string)
%%BOTIRCSERVER       IRC server the bot is connected to (string)
%%BOTONLINE          time the bot is connected to %%BOTIRCSERVER (string)
%%BOTNETBOTS         list of bots in the botnet delimited by , (string)
%%BOTNETSIZE         botnet size (integer)
%%BOTNETUSERS        amount of users in the bot channels (integer)
%%BOTUSERLIST        bot's userlist length (integer)
%%BOTUPLINK          bot's uplink (string)
%%BOTDOWNLINKS       bot's downlinks (string)
%%BOTUPTIME          bot's uptime (string)
%%BOTOFFSET          bot's offset (string)
%%BOTTIMEZONE        bot's timezone (string)

That's all you need to know to make your own HTML templates. As this
may sound rather complicated at first glance, it isn't. Just have a
look at the templates that come with the tarball and you'll quickly
understand how it works. You may also want to open them in your
favorite HTML authoring program and start trying. Here are some easy
examples:

EXAMPLES
*********************************************************************

1. You want a listing of all users currently on your channel:

<HTML>
<BODY>
Current users in %%CHANNEL
<TABLE WIDTH=640>
<!-- ChanUsers 0,0 -->
<TR>
<TD>!!USER</TD>
<TD>!!HOST</TD>
<TD>!!DUR</TD>
<TD>!!IDLE</TD>
</TR>
<!-- End of ChanUsers -->
</TABLE>
</BODY>
</HTML>

That's all.
First, we mention the name of the channel: it's %%CHANNEL
Then we open a table because we want to use rows and columns.
Then we start the listing with <!-- ChanUsers 0,0 -->.
Now, we open a row via <TR>
In the first column (<TD>), we put the user's nick (!!USER), then
close the column (</TD>).
In the next columns, there will be the user's host, his duration
in the channel and his idletime.
Close the row, we won't put more information in there.
The listing is done, so let's close it: <!-- End of ChanUsers -->
Finally close the table and we are finished.

2. Now, you also want to add the TopVisitors to the same webpage:

<HTML>
<BODY>
Current users in <FONT COLOR=RED>%%CHANNEL</FONT>
<TABLE WIDTH=640>
<!-- ChanUsers 0,0 -->
<TR>
<TD>!!USER</TD>
<TD>!!HOST</TD>
<TD>!!DUR</TD>
<TD>!!IDLE</TD>
</TR>
<!-- End of ChanUsers -->
</TABLE>
The TopVisitors are:
<TABLE WIDTH=640>
<!-- TopVisitors 300,10 -->
<TR>
<TD>!!RANK</TD>
<TD>!!USER</TD>
<TD>!!VALUE</TD>
<TD><IMG SRC="redbar.gif" HEIGHT=10 WIDTH=!!WIDTH> !!PERCENT</TD>
</TR>
<!-- End of TopVisitors -->
<BR>
People's total online time in %%CHANNEL is %%TOTALONLINE.
</TABLE>
</BODY>
</HTML>

Quite similar to the first example, but there's something new: the
definiton of the bar's width. For every bar drawn, the width is
different, and the script needs to know where to put the
appropriate value. Therefore the width can't be constant at e.g.
50 pixels, instead we need to insert the variable !!WIDTH

That's it. I explained this to the best I can. Let me add I will not
make any customized templates.