After installing the package properly:
More details after:
The recommended method to install MaxMind IP-GeoLoc, is simply using your target website marketplace page. However, if you wish not to use concrete5 internal feature, you can follow the next instructions:
During the installation, you will be prompted a few options first:
Before you install the addon, you can already set a few settings parameter:
Those settings will be freely modifiable after installation from thepage.
At the end of the installation, the addon will check if any database is provided, and will suggest you to go the database page if you don't have any installed.
After installing MaxMind IP-GeoLoc (either through downloading or preferably directly through your concrete5 website interface), you will be provided with the Maxmind GeoIP Redirect and Message block and the Maxmind IP GeoLoc Redirect page attribute.
MaxMind IP-GeoLoc also installs a few dashboard pages under its own sub menu.
MaxMind IP-GeoLoc needs the Maxmind GeoLite2 or GeoIP2 database installed on the server. You can install this in different ways: different methods from the > > Page:
Following your initial installation, no database will be installed (this addon does not ship a MaxMind GeoLite2 database), so the list of database will be empty. In order to use the IP geolocalisation features, you will need to download the MaxMind GeoLite2 database using one of the following method:
MaxMind IP-GeoLoc can automatically download the latest version of MaxMind GeoLite database. To do this, go to the > > page, and then click on the button. Maxmind GeoIP will then automatically download and install the latest MaxMind GeoLite database.
You can also download the MaxMind GeoLite database from the automated Jobs page of your website :
If you can't use the automatic downloader for some reason, you can still upload the Maxmind GeoLite2 database directly through the dashboald page. First, go to the> > page, and use the provided upload form.
In case everything fails, you can still upload the MaxMind GeoLite2 City database or the commercial version of GeoIP database into the packages/gnt_maxmind/data directory. The uploaded file must be named according to the following scheme : YYYYMMDD-HHMMSS-maxmind-geoip2-city.mmdb for example 20131205-230640-maxmind-geoip2-city.mmdb.
You can download the free version of MaxMind GeoLite2 database here : http://dev.maxmind.com/geoip/geoip2/geolite2/.
You will need to download the "GeoLite2 City" archive and uncompress it first before you upload it to your server. To find the correct storage path, go to the Maxmindpage:
To add a customized message into a page, add an instance of the Maxmind GeoIP Redirect and Message block on that page, and fill in the message in the add/edit interface.
The Known location message will be outputted for visitors whose IP can be matched to a country. In this message the following patterns will be replaced :%COUNTRY% :the country name (in the current locale)%COUNTRY_CODE%:the country ISO code%COUNTRY_XX% :the country name in the XX locale, (eg: en for English)%STATE_XX% :the state name%STATE_CODE% :the state ISO code (eg: WA or 75 for Paris-France)%STATE_XX% :the state name in the XX locale, (eg: Washington State)%CITY% :the city name (in the current locale)%CITY_XX% :the city name in the XX locale, (eg: 'en' for English)%IP% :The visitor IP address
for instance the following message :
Hello visitor from %COUNTRY%, did you know in Chinese your country name is written %COUNTRY_zh-CN%?
will be seen as
Hello visitor from United States, did you know in Chinese your country name is written 美国?
by a visitor from the US, and :
Hello visitor from France, did you know in Chinese your country name is written 法国?
by a visitor from France.
The Unknown location message will be outputted for visitors whose IP can not be matched to a country. In this message you can use the same patterns, as the preceding, but for obvious reasons only the %IP% pattern will be replaced by by a meaningful value. All other patterns will be replaced by an empty string.
If you want to lookup a specific IP address, you can go to the> > page :
By default the IP address filled in the IP text field is your public IP address (more precisely your IP address visible from the server). The preceding screenshot shows a randomly picked IP address.
Several information will be printed
One of the most powerful feature this addon will give you is the ability to create various type of redirections for visitors based on their country/city or simply their IP address. To do so, you must process as follow:
Lets detail each step:
To create a new redirection rule set (or to modify an existing ruleset) go to the> > page.
From that page, click on thebutton.
Each redirection rule set contains two parts :
The General options of a rule set will let you enable or disable the rule set, set a specific name for this rule set (used to select the rule set from the message block or from the page attribute), and set the default message used in case of suggested redirection.
The message entered can contain the same patterns as the block message:
as well as the following rule specific pattern:
the %TARGET_A_OPEN% and %TARGET_A_CLOSE% can be used to create a link to the redirection target inside a redirection message.
By default, the redirection rule set is empty :
Click on theto create a new rule.
You can create multiple rules. Rules are applied from top to bottom. Rules can be be reordered by dragging a rule.
Each rule can be activated or deactivated individually using the activation switch. When a rule is activated (through the activation switch), a rule need to match all the conditions set in the Matching section on the rule.
Currently, 3 match types are available :
Each matching (except no match) accepts a parameter against the visitor corresponding data (country/city/state/ip) is checked. The parameter input becomes visible when the corresponding match type is selected. The input accepts the following format:
If your application needs a specific matching, or if you are unsure if those matching types will, let you achieve your goals, please contact us.
If a rule is activated, the redirection is then executed (the following rules are then ignored). If a rule is not activated, MaxMind IP-GeoLoc will then check the next rule in the list.
Each rule have a Redirect type, and a target. Redirect types can be one of the following choices :
The Suggest Redirect target type will display a message on the page (this message can be positioned and configured, see bellow). The message shown is either the rule set global message or the specific message of the rule (if selected). This type of redirection will let you show the message for a specific amount of time (timeout). The user will be redirected to the target at the end of the timeout if the hide on timeout is not selected.
The redirection will redirect to a target. Currently the available targets include :
Finally, each rule can be configured through the following options:
To apply a redirection rule set to a page, the easiest way is to add the Maxmind IP GeoLoc Redirectattribute to the selected page :
The page attribute can be activated for the page, or for the page and all its sub-pages (child pages). Beware, activating the attribute on the home page will activate it on all pages on the website (since the home page is the parent of all pages.
Using this method, you can easily create page trees accessible by only a specific IP/country/city etc…
You can also use the Maxmind GeoIP Redirect and Message block. Using block to perform redirection will also allow you to perform that redirection on multiple page (for instance through Stacks).
In case you want to disable all redirection rules temporary, you can do so by disabling the redirection in the> > page :
MaxMind IP-GeoLoc comes with 2 jobs :
It is advised to update at least once a month the database either using the Download Maxmind db job. If you automate the download job, then you may want to automate the delete job as well so that your data folder does not grow too big.page or by running the
Sometimes you need to trace a little how rules are really applied and what happens for what IP. MaxMind IP-GeoLoc provides several tools to help you:
You can activate debug traces in different places:
When logs are activated on a specific rule (and the page where the rule had been placed is viewed by any visitors), a complete log of actions is added to concrete5 logs, accessible at http://yoursite.com/index.php/dashboard/reports/logs.
If you want to check what would be displayed for a specific IP address, and know which field are avaiable, use the lookup page and enter the address in it.
In order to know exactly where a specific user would be taken, you can simulate that visitor IP. You can either set a fixed IP for all visitors in thepage, or set a simulated IP by adding a parameter to the URL query. The name of the variable is customizable in the page.
In the Allow IP simulation (debug), select box:page, simulation can be set to several option, using the
For example, if you selected the GET VARIABLE method, and used MAXMIND_IP, to simulate a visitor coming from the IP 22.214.171.124, you could visit the url: http://yoursite.com/path/to/my/page?MAXMIND_IP=126.96.36.199.
By default MaxMind IP-GeoLoc stores the databases files under the application/files/gnt_maxmind directory. This directory will be created if non existing. That way, updates won't delete downloaded databases. If you wish to change this, go to the page:
Activate the checkbox left to the storage path to access to the move location options:
Enter a new location in the text field, the new directory must be writable if existing, or its parent must be existing and writable if not. If the target directory does not exist, MaxMind IP-GeoLoc will attempt to create it. Options are given to know what to do about existing databases (either copy them, move them, or leave them).
The default behavior upon un-installation is to leave the databases where they are. If you wish to remove the databases upon uninstallation, change the corresponding setting in thepage.
MaxMind IP-GeoLoc uses noty js to create the messages shown on suggested redirections. To install other themes for your messages, you can install those themes in one of the following locations:
layouts can be installed in the following locations:
Additionally, one can package new themes or layouts by placing them into a gnt_maxmind/js/3rdparty/noty/themes or gnt_maxmind/js/3rdparty/noty/layouts directory respectively.
Your themes or layout must be named after the name of your js file suffixed with "Theme". For instance if your theme is named beautiful.js then your theme must be named beautifulTheme.
Incidentally, you can overwrite the default theme by copying the default.js file shipped with the package into your site override and respectively for layouts).
You can also create or redefine the provided layouts by adding a file (or copying it) in your site override application/js/3rdparty/noty/layouts directory (or any place listed above).
More information on noty can be found here http://needim.github.io/noty.
Although this addon had been tested with and without the maxminddb C extension installed, the author does not provide free installation or support service for this C extension. If you need support concerning this point, please contact us for a quotation.
If you need any assistance regarding this addon, please use the support forum directly.
In case you need a new feature, or anything else, feel free to contact me through concrete5 PM system, or contact us directly.