.. You may want to use the usual include line. Uncomment and adjust the path. .. include:: ../Includes.txt =============== EXT: dmc\_geoIP =============== :Author: Kasper Skårhøj :Created: 2002-11-01T00:32:00 :Changed: 2005-06-09T10:07:44 :Author: Dominique Stender :Email: dst@dmc.de :Info 3: :Info 4: .. _EXT-dmc-geoIP: EXT: dmc\_geoIP =============== Extension Key: **dmc\_geoIP** Copyright 2005, Dominique Stender, This document is published under the Open Content License available from http://www.opencontent.org/opl.shtml The content of this document is related to TYPO3 \- a GNU/GPL CMS/Framework available from www.typo3.com .. _Table-of-Contents: Table of Contents ----------------- **EXT: dmc\_geoIP 1** **Introduction 1** What does it do? 1 Users manual 1 **Adminstration 1** detailed workflow 1 **Configuration 2** Configuring country rootpages 2 Configuring the ISOType 2 disabling redirects 2 Reference 2 The MaxMind geoIP country database 2 **Known problems 3** **To-Do list 3** **Changelog 3** .. _Introduction: Introduction ------------ .. _What-does-it-do: What does it do? ^^^^^^^^^^^^^^^^ The dmc\_geoIP extension uses the free database by MaxMind to determine the country of residence for visitors based on their IP address. The extension will make sure every visitor browses the correct rootpage tree for his country of residence. So for example certain pagetrees can be denied to users from specified countries. .. _Intended-uses: Intended uses """"""""""""" This extension will be useful for sites that provide localized content for clients from various countries. So if visitors from the USA are meant to see only the pages within the 'us' pagetree, while visitors from other countries are allowed to gain access to their intended pagetree the extension does just that. Other uses might be localized advertising, pre-filling of form fields and many other – country related – tasks. .. _Users-manual: Users manual ^^^^^^^^^^^^ The dmc\_geoIP extension is an include only extension and provides no GUI whatsoever. .. _Adminstration: Adminstration ------------- Typo3 administrators can edit TypoScript setup parameters to configure the extension. If the country of residence for a visitor could be found, the corresponding ISOCode will be written in TypoScript setup: :: modules.tx_dmc_geoip.countryOfResidence .. _detailed-workflow: detailed workflow ^^^^^^^^^^^^^^^^^ The dmc\_geoIP extension is included as library upon every pagerequest. So on every page request the extension tries to find the country of residence for the requesting IP. If the country can be determined – the IP is found in the MaxMind geoIP database – the extension reads its TypoScript configuration and looks for a pageID configured for the country determined in step 1. If a (root) pageID is configured for the country of residence the extension checks whether the currently requested page lies within the rootline of the pageID found in step 2. If that is the case no action is performed. If the currently requested page does not lie in the rootline found in step 2 – and thus the currently requested page is invalid – a Location Redirect header is sent ot the browser with the appropriate root pageID. No redirection will be performed if the extension is configured not to do so (see below). .. _Configuration: Configuration ------------- .. _Configuring-country-rootpages: Configuring country rootpages ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Currently the most important option to configure the dmc\_geoIP extension is to provide pageIDs of rootpages within the Typo3 pagetree for certain country ISOCodes. This is done via TypoScript setup .. _generated: ((generated)) """"""""""""" .. _Example: Example ~~~~~~~ :: modules.tx_dmc_geoip { country.rootpages { US = 45 DE = 1241 } } The dmc\_geoIP uses the two-letter ISO 3166 standard to identify countries by default – for other configurations see below. So the configuration above tells the extension that every visitor with an IP residing in the USA may only visit pages that lie within the rootline of the page with Id 45, while visitors from Germany may browse the pages within the rootline of page 1241 only. Additional countries can be configured likewise. Visitors from unknown or not configured countries visit the website are unaffected and may browse freely through all pages. .. _Configuring-the-ISOType: Configuring the ISOType ^^^^^^^^^^^^^^^^^^^^^^^ Other than the two-letter ISO 3166 standard (which is used by Typo3) the dmc\_geoIP extension can be configured to request three-letter ISOCodes (US becomes USA, DE becomes DEU, etc). .. _generated: ((generated)) """"""""""""" .. _Example: Example ~~~~~~~ :: modules.tx_dmc_geoip { isoType = 3166-3 } .. _disabling-redirects: disabling redirects ^^^^^^^^^^^^^^^^^^^ It might be useful to have the dmc\_geoIP extension determine the country of residence for your visitors, but still allowing everybody to see everything. If thats the case the extension must be configured in such a way that no redirect is performed. This can be done as follows: .. _generated: ((generated)) """"""""""""" .. _Example: Example ~~~~~~~ :: modules.tx_dmc_geoip { redirect = 0 } .. _Reference: Reference ^^^^^^^^^ .. ### BEGIN~OF~TABLE ### .. _country-rootpages: country.rootpages """"""""""""""""" .. container:: table-row Property country.rootpages Data type Array Description Configures (root) pageIDs for country ISOCodes Default .. _isoType: isoType """"""" .. container:: table-row Property isoType Data type String Description Determines the type of ISOCode the extension uses internally and that will be written to the countryOfResidence property. Default 3166-2 .. _CountryOfResidence: CountryOfResidence """""""""""""""""" .. container:: table-row Property CountryOfResidence Data type String Description Contains the country ISOCode of the requesting IP. Default The empty string .. _redirect: redirect """""""" .. container:: table-row Property redirect Data type Boolean Description Determines whether the extension performes a redirect to the correct rootpage for the country of the visitor or not. Default true .. ###### END~OF~TABLE ###### .. _The-MaxMind-geoIP-country-database: The MaxMind geoIP country database ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The dmc\_geoIP extension relies on the geoIP country database from MaxMind, available freely on `http://www.maxmind.com `_ The database is licensed under the open data license. The database is updated on a regular basis, so a cronjob should be configured to download the current database once in a while. This is the only way to make sure the IP to country mapping of the dmc\_geoIP extension is always up to date and generates as much correct results as possible. As of now the most recent geoIP database can be obtained here: `http://www.maxmind.com/download/geoip/database/geoIP.dat.gz `_ It has to be installed into the 'geodata' subdirectory of the extension directory. MaxMind also provides a free PHP library licensed under LGPL that accesses that database. The dmc\_geoIP extension already comes with that PHP library. It is the original code as provided by MaxMind. The only addition that has been made is the function geoip\_countrycode3\_by\_addr() which maps an IP to a three-letter ISO 3166 code. The library can be found in the 'lib' subdirectory of the dmc\_geoIP extension. .. _Known-problems: Known problems -------------- Error handling might need some more improvement. .. _To-Do-list: To-Do list ---------- Provide a Typo3 Backend GUI to download the most recent version of the MaxMind geoIP country database. .. _Changelog: Changelog --------- .. _generated: ((generated)) ^^^^^^^^^^^^^ .. _1-0-3: 1.0.3 """"" reimplemented maxminds geoip library for better integration into the Typo3 environment. E.g. All methods have been moved into a class, have been renamed to studlyCaps syntax and error handling has been improved. Errorhandling is still not perfect though. .. _1-0-2: 1.0.2 """"" first public release |img-1| EXT: dmc\_geoIP - 3 .. ######CUTTER_MARK_IMAGES###### .. |img-1| image:: img-1.png .. :align: left .. :border: 0 .. :height: 32 .. :id: Graphic1 .. :name: Graphic1 .. :width: 102