chCounter v2.3 ReadMe


Welcome!

chCounter is a textcounter with detailed statistics.
Features:

  • The counter itself shows:
    - total visitors, visitors today/yesterday/per day/max per day
    - max. online/max. online per day
    - page impressions at all/today/yesterday/per day/of the current page
  • The statistics provide a view of:
    - pageviews altogether, today, yesterday, average pageviews per visitor,
       average visitors/pageviews per day
    - the users being online with their IP, current page, last activity, pageviews
    - the most requested pages
    - homepages and domain your visitors come from (Referer)
    - browser + OS of the visitors, detailed version info concerning IE, Opera, Mozilla,
       Netscape, Windows
    - most frequent user agents
    - language settings of the users
    - search words (search engines)
    - monitor resolutions
    - visitors with activated javascript in percent
    - statistical distribution of visitors (within a day / week)
    - visitors/pageviews last 4 weeks / 12 months / years
  • Comfortable administration interface:
    - counter values are arbitrarily changeable
    - each statistic may be individually (de)activated
    - many options concerning the counter, its counting behaviour and the statistics
    - log data: displaying the visitors' data (IP, Host, date, time,
       user agent, referer and requested pages)
    - comfortable generation of the counter's include code
    - news page which informs you about new chCounter versions or similar news
  • The layout of the counter can be perfectly customized via templates.
  • Visible or invisible, for each page separately definable.
  • May be active or inactive.
    The admin can get optionally a cookie to prevent him getting counted, too.
  • Integration of the counter possible via PHP or JavaScript
  • Quick & easy installation routine
  • Fast and capable by the use of PHP and MySQL
  • Optimized for register_globals = off and error_reporting(E_ALL)

System requirements


  • Webspace with
    - PHP 4.0.5 or higher
    - a MySQL - database
    - FTP access

Installation


In this chapter you will be lead through the chCounter installation.

1. configuration file

First, there must be made some changes in the file config.inc.php in the directory /include:

$chCounter_dbconfig['server']
Name of your database server. Often localhost.

$chCounter_dbconfig['user']
Your database account.

$chCounter_dbconfig['passwort']
YOur password for your database account.

$chCounter_dbconfig['database']
Name of the database.

Furthermore, you can find in the config file the default names for the chCounter database tables, and environment variables. They usually don't need to be edited.


3. Customize the templates

Open in the directory /templates of the counter and change the layout of the counter, if you want to.

4. Upload the counter files und directories

Upload now all files and directories (apart from update.php, analyse_useragents.php) with your ftp accountper FTP to your webspace into any directory.

5. Online installation

Now follows the real installation via web interface:
Open the file install.php in the counter directory with your internet browser und follow the installation routine.

6. Administration panel

Log in the administration area at

http://www.yourdomain.de/pathtoscript/administration/index.php

and customize the counter as far as you want.

2. Insertion of the counter into your homepage.

In the administration area under "help" you can create your individual code to include the counter. Neverless, here's a tutorial:


Including with PHP

The site where you use PHP-Code must have the file extension *.php, otherwise the PHP-Code won't be parsed.
Add at the area where want to counter to be included the following code:

        <?php
        include("PATH_TO_SCRIPT/counter.php");
        ?>

PATH_TO_SCRIPT must be replaced with the path to the counter directory (relative or absolute from server root, not a path with "http://"!). The layout of the counter is set in the template file "templates/counter.tpl.html".
If you want to include the counter invisible, you have the add behind "<?php" the following line:

        $chCounter_visible = "0";

If you add the following line, the counter will be inactive:

        $chCounter_status = "inactive";

If you want that the counter is displayed in a different layout as defined in the template file "counter.tpl.html", you can assign an individual template:

        <?php
        $chCounter_template = <<<TEMPLATE
        Here comes the individual template, e.g.
        visitors: {TOTAL_VISITORS}<br>
        online: {VISITORS_ONLINE}
        after this line here ends the template
        TEMPLATE;
        include("PATH_TO_SCRIPT/counter.php");
        ?>

You can find the needed placeholders in the template file.
Important: In the line

TEMPLATE;

must not be noted anything else (the line must not be intended with blanks, too)!!



Including the counter with JavaScript

Alternativly can be included with JavaScript (thus the file into which the counter is included doesn't need the extension "php"). Anyway, use JavaScript to include the counter only, if PHP is absolutely not possible.
As the JS-Code is a little more complex, it's not described here. In the administration area you can easily create the code that you need.
Important: Never put the JavaScript code into a noframes-area! In this case the browsers may usually not execute the code, so the counter can't work.



That's all yet,
ready! :-)


Administration Area


The following subpages are available:
  • Configuration
    here you can change the values or customize the preferences.
  • Change user data
    if you want to change your password, user name etc.
  • Visitors log data
    Listing of the visitors with date, user agent, referer,...
  • Statistics
    Just a link to the public statistics page
  • Help
    Here is the code displayed which you need to included the counter.
  • News
    Here you can get the latest chCounter news.
  • Log out
    To log out of the administration area.

Documentations


Some functions and/or attributes of the counter script are more precisely described here.

Templates

The template files are located in the directory "templates/". The templates are responsible for the layout of the files counter.php, statistics.php and onlineusers.php, you can customize them (nearly) completely.

Special placeholders, encluded within curly brackets are later replaced with the corresponding content. Placeholders can be deleted without any problem to suppress for example the output of a special value.
Templates can be also defined locally within the PHP code which includes the counter, for more information see here. For the locally defined templates apply the same rules as mentioned above.


Page Titles

In order not to show the file names and paths as title in the online users- and pages statistics, the counter searches in die file in which the counter is included for one of the following tags:
  • <chCounter_title>HERE_COMES THE PAGE_TITLE</chCounter_title>
    If the counter finds this tag in the page, the content of this tag will be used as page title.
  • <title>HERE_COMES THE PAGE_TITLE<</title>
    If the counter can't find the tag mentioned above, it will try to find the HTML title tag of the page.
Keep in mind that the counter cans only the file, in which the code for the counter inclusion is noted: if the title-tag is in another file to include, it won't be detected.
Alternatively, a page title can be assigned directly in the php code. To use this function must be added the following line before the include command:

        $chCounter_pagetitle = "HERE_COMES THE PAGE_TITLE";


Homepage-URL

In the administration area, the URL of your homepage must be specified. If you have xour own domain, it would look like:

http://www.domainname.tld/


If you don't have an own domain and your homepage is available under e.g. www.domain.tld/members/name/, the URL must look like:

http://www.domain.tld/members/name/.

It's important that you insert the whole path to your homepage root, not only the domain name. If you use a redirection, e.g. like "www.mydomain.de.vu", don't insert this address, but the real address of your homepage files.


Miscellaneous

FAQ's

The counter isn't visible, only the PHP code is displayed in the page source code!
- see here.

Is it sufficient to include the counter into one page? Will all other pages be counted, too?
- No, that's not sufficient. The counter can only count, when the script is executed -> you have to include the counter into each page where you want to count the visitors or page impressions.

Update from version 2.1.x or 2.2.x to 2.3

  • Open and edit the file include/config.inc.php of the new chCounter version.
  • Upload all (!) files and directorys of the new version / overwrite the old ones.
  • Open the file update.php with your web browser and follow the instructions.
  • Open the file analyse_useragents.php with your web browser.

History

Here a list of the chCounter versions:

v2.3 - 03|07|2004
Code-internal changes, improvements of the referer/agent statistics and an enlargement of the statistics page, two new statistics. Many further improvements and some smaller features added. Some bugfixes.

v2.2.1 - 08|19|2003
Small bugfixes

v2.2.0 - 08|17|2003
New statistics: monitor resolutions and search engines: searched words, now bilingual (German/English), lots of smaller new features, optimizations, a few bugfixes.

v2.1.1 - 04|05|2003
Elimination of two minor errors bugs, MySQL class updated, improvements of referer counting and version detection of Netscape browsers, file code.php Added, + some further changes

v2.1 - 03|07|2003
Bugfixes, extensions, big modification of the source code

v2.0 - 02|18|2003
Second and higly extended version

v1.03 - 07.01.2002
Some bigger problems with PHP versions < 4.1.0 because of missing superglobal variables -> fixed

v1.02 - 01|06|2003
The number of visitors to show per page in the administration area is now customizable.
Besides no other changes.

v1.01 - 01|04|2003
Bugfix: the value "users yesterday" wasn't displayed correctly.
License changed.

v1.0 - 01|03|2003
First published version of the chCounter.


License

chCounter, Copyright by Christoph Bachner, 2004

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

chCounter 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 chCounter; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


Contact


(c) by Christoph Bachner, 2004