Latest revision as of 20:06, 25 August 2015

I'm not a native English speaker. Please correct my mistakes.

In the display appears the hits and visits from the current day, as well as the respective total. Statistic is also in the backend.

Hint:

This page is no longer updated by the developer. The current manual for the extension Visitors can be found here: docs.contao.ninja

Forum

Questions about the Visitors module will be answered in forum: Forum
Errors and requests can be reported at GitHub: Issue Tracker.

Translations

Translations can be performed on Transifex

Installation

The installation of the module occurs about the extension Repository in back end of Contao.
A manual installation is possible. Download the ZIP file from Extension Repository, unzip and transfer it.
A directory should have been created "/system/modules/visitors".
Then call /contao/install.php - Perform Update Database.
( /typolight/install.php in older TYPOlight installations )

The module Visitors is dependent on the module "Bot Detection" and "Excel 95 writer (xls_export)". They must therefore be installed with manual installation.

Note for older "TYPOlight/Contao" versions

Contao 2.9

Users of Contao 2.9.x, please use Visitors Module Version 2.7.1 (Direct Link)

TYPOlight 2.8

Users of TYPOlight 2.8.x, please use Visitors Module Version 1.7.2 (Direct Link)

TYPOlight 2.7

Users of TYPOlight 2.7.x, please use Visitors Module Version 1.4.1 (Direct Link)

Update version 1.x to version 2.x

Caution: Version 2.x is not fully compatible with previous versions, an update is possible.

What is to be observed, can be found here.

• Visitors Update Version 1 to Version 2

Overview

The Visitors module contains two back end and one front end module.
In the back end, there are "Visitors" and "Visitor Statistics", for the front end "Visitors".

Back end

Visitors

Visitors Statistics

shows in detail: (Click on image for higher resolution)

• Visitors Statistics
• 

  Visitors Statistics

• 

  Browser Statistics

• 

  Search Engine Referer Statistics

Front end

For the front end are provided two CSS files as an example:

• mod_visitors_fe.css for the normal output, line by line
• mod_visitors_fe_horizontal.css for the horizontal output

Visitors Statistics

Visitors Statistics, horizontal

Using

The first one creates a new visitor category via the menu item "visitors". In this then the counter.
Then, create a front end module and build it into the layout of the page.
Here are the steps, each with the default values. Technical details will be explained later.

Create the category

To create a new category, just click on the left in the back end in 'content' to 'Visitors'. In the main area click on the button 'New category'.

There, enter the name of the category. The front end module will later use this name. Then you click on "Save and close".
Now you can see the category overview. By clicking on the pencil in the line of the category and repeated clicking on the pencil in the head of the category you return to the settings of the category.

Create new counter

In the category list now clicking on Edit (pencil) of the category.
Now, either click the 'New counter' and then the arrow icon, or click the plus in the head of the category:

Now, some information are needed: :

• Name, (is displayed as a heading on the numbers).
• Start date, optional, only for display in font end
• Optional: 'Initial value of visitors/hits'
• Optional: 'Visitors per day'
• Activate "Published"

Then you click on "Save and close".

Front end Module

A new front-end module is create with:

• Layout -> Themes -> Modules -> Add module (Contao 2.9)
• Layout -> Modules -> Add module (TYPOlight 2.8.x)

At first, enter the title, and only then select in "Module type": 'Miscellaneous'-'Visitors'. It changes the form fields.
In 'Visitors category' now select the previously created category, then 'Save and close'.

Now, the front end module must be included in the layout:

• Layout -> Themes -> Layout -> Edit the used layout (Contao 2.9 and newer)
• Layout -> Page layout -> Edit the used layout (TYPOlight 2.8.x)

Include in 'Included modules' the just-created front end module (e.g. to left)

CSS-File

As mentioned above, are provided two CSS file for presentation.
For the first tests you should copy the file mod_visitors_fe.css from /system/modules/visitors to /tl_files . Then import them over the back end and activate it in the layout.

Technical Details

Technical details are inside of the category, in the counter denifinition and in the constructed front end module feasible / adjustable.

Technical Details inside of the category

Counting mode

From version 1.6.0, Counting mode is selectable, server side or browser side, by category:

• Load counting, server side by Contao
• Read counting, client side by browser
  • (only on Contao cacheMode: server and browser cache / only browser cache)

With "Read counting" can be counted when the page is in the browser cache and will be called from it. The system setting "Cache mode" will be respected.

Note:

The display of current values will continue but only if the page is requested from the server.

Technical Details inside of the counter denifinition

Block time

The block time is in seconds. After interruption of the requests at this time, an access is counted as an additional visitor.
Pre-entered are 1800 seconds, so that is 30 minutes.

Technical Details in the front end module definition

Templates

Each module can be assigned its own Template. Four different templates are included.

• mod_visitors_fe_all
  • All fields are included. (see example above)
• mod_visitors_fe_hits
  • Here the visit rows were removed.
• mod_visitors_fe_visits
  • Here the hit rows were removed.
• mod_visitors_fe_invisible
  • Here, nothing is displayed. This template is used for a pure counting.

For own Templates, the template files must start with "mod_visitors_fe_" and end with ".html5" or ".xhtml".

Show to guests only

Hide the module if a member (front end user) is logged in.

Protect module

Show the module to certain member groups only.

No counting for this HTTP_USER_AGENT partial identifier

You can set a custom UserAgent String in your browser and in the visitors module configuration.

• Layout -> Themes -> Modules -> Module Name (Contao 2.9)
• Layout -> Modules -> Module Name (TYPOlight 2.8.x)

In the field: "No counting for this HTTP_USER_AGENT partial identifier", you can enter a unique identifier.
Example: CTISOK
Save it.

Now, change the User Agent String of Mozilla Firefox:

1. Type about:config in the Mozilla Firefox address bar and press ENTER,
2. Type general.useragent.extra.firefox in the Filter bar,
3. Double-click on the returned Firefox setting, where you can change a user agent string to overwrite the default.
4. Add her "CTISOK" separated by space, e.g. "Firefox/3.5.2 CTISOK".

You can check your new User Agent String , type about: + ENTER in the Mozilla Firefox address bar and press ENTER, see last row.

For other browsers, see: walkernews.net - how to change user agent string

Hint:

This does not work anymore in Firefox 4. Alternatively, use the add-on: User-Agent-Switcher

Insert-Tags

Show the values

From version 1.2.0 there is Insert-Tags to show the values.

 {{visitors::catid::name}}
 {{visitors::catid::online}}
 {{visitors::catid::start}}
 {{visitors::catid::totalvisit}}
 {{visitors::catid::totalhit}}
 {{visitors::catid::todayvisit}}
 {{visitors::catid::todayhit}}
 {{visitors::catid::averagevisits}}

From version 1.5.0 and from TYPOlight 2.8, Insert-Tags can be extended with prefix 'cache_'. Thus, these then cache resistant.

 {{cache_visitors::catid::name}}
 ...

The counting is continued through the module! Who wants to use to display the insert tags, the module continues to need, but only to count. With the templates mod_visitors_fe_invisible the module may be invisible, if desired.

To determine the category ID, go into the category overview of the module with your mouse over the "i".
From version 2.3.1, the ID is shown right behind the category name.

The tooltip displays the ID.
Or click on the "i", in the following site is in the first line the ID.
For category ID = 1 that would be like that:

 {{visitors::1::online}}

Count

An alternative to "counting only" would be to use an Insert-Tag. From version 1.5.0 there is another Insert-Tag. The module itself uses this as well:

 {{cache_visitors::catid::count}}

Example for installation in an article (for category ID = 1):

 <span style="width:0px;height:0px;">{{cache_visitors::1::count}}</span>

Caution: It must be noticed, that the insert-tag for the count will be installed at first on the page so that the counting is carried out before the identification of the values.

More Insert-Tags

From version 2.1.0, there ist Insert-Tags for display the values of the day with the most visitors.

 {{visitors::catid::bestday::date}}   - Day (Date) with the most visitors
 {{visitors::catid::bestday::visits}} - Number of visitors of the day with most visitors
 {{visitors::catid::bestday::hits}}   - Number of hits of the day with most visitors
or
 {{cache_visitors::catid::bestday::date}}
 {{cache_visitors::catid::bestday::visits}}
 {{cache_visitors::catid::bestday::hits}}

The "date" insert-tag has an optional parameter to format the date output. (m.d.Y , Y-m-d, etc.)
The system setting is used as default. As a separator, a "::" are used.
A complete example (with category 1):

 Best Day: {{visitors::1::bestday::date::j. F Y}} with {{visitors::1::bestday::visits}} visitors 
(and {{visitors::1::bestday::hits}} hits)

results:

Best Day: 31. August 2010 with 25 visitors (and 123 hits)

Specific feature

No counting

No front-end call is counted when one is logged on at the same time in the back end.

Visitors per day: Ø = 0

The average value per day will be calculated for each full calendar day.
So, having only one day before a counting or a counting of the current day, no meaningful value can be calculated.
(average = number visitors)
In these cases appears "0".

Bot Detection off

Who wants to count the hits from bots and search engines can switch off the bot detection. This is done by the file localconfig.php.

Caution: This applies to all Visitors modules when several front end modules have been created!

The following entry to the end of localconfig.php (after: ### INSTALL SCRIPT STOP ### ) switching off the bot detection:

$GLOBALS['TL_CONFIG']['mod_visitors_bot_check'] = false;

--BugBuster 00:42, 12 December 2010 (CET)