Installation

Package installation

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:

1. Download the zip archive
2. Uncompress the zip archive into your packages/ directory
3. Ensure the directory packages/gnt_maxmind/data is writable by the server
4. Visit your Add Functionality page (located at http://yoursite.com/index.php/dashboard/extend/install )
5. Click on the MaxMind IP-GeoLoc Install button

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 Maxmind GeoIP sub menu.

Upload Maxmind GeoLite database

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 Dashboard>Maxmind GeoIP>Databases 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 Dashboard>Maxmind GeoIP>Databases page, and then click on the Download Latest MaxMind GeoLite Free 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 Dashboard>Maxmind GeoIP>Databases 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.

Average Users

Adding a Customized Message

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)
• %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.

Lookup an IP

If you want to lookup a specific IP address, you can go to the Dashboard>Maxmind GeoIP>IP GeoLoc Lookup 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.

Creating Redirection Rules

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:

1. Create a redirection rule set (in Dashboard>>Maxmind GeoIP>Redirection)
2. Add redirection rules to it
3. Save the redirection rule set (and activate it)
4. Use the redirection rule set from a message block or from a page attribute

Lets detail each step:

To create a new redirection rule set (or to modify an existing ruleset) go to the Dashboard>>Maxmind GeoIP>Redirection page.

From that page, click on the Create New Rule Set button.

Each redirection rule set contains two parts :

• The General options (applicable to each rules)
• The redirection rules themselves

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:

• %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)
• %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

as well as the following rule specific pattern:

• %TARGET_URL% the redirection target URL
• %TARGET_A_OPEN% the redirection target a open tag (to create a link)
• %TARGET_A_CLOSE% the redirection target a close tag (to create a link)

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 the Add a redirect Rule to 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 :

• Match the visitor Country Code (no match, equal, not equal, or using a regexp)
• Match the visitor City Name (no match, equal, not equal, or using a regexp)
• Match the visitor IP address (no match, equal, not equal, or using a regexp)

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 :

• No redirection
• Forced HTTP Redirection
• Suggest Redirect

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 :

• No target (therefore, no redirection)
• To a specific page of the website
• To an external url

Finally, each rule can be configured through the following options:

• exclude users  if enabled, this rule will not affect logged in users
• exclude admins  if enabled, this rule will not affect logged in admins
• hide on timeout  if enabled, do not redirect the user, just hide the message
• modal message  if enabled, make the message modal (the user must click on it)
• type  message type (alert, info, success, error)
• position  position of the message on the screen (top/bottom left/middle/right)

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

Advanced Users

Globally Deactivating all Redirect Rules

In case you want to disable all redirection rules temporary, you can do so by disabling the redirection in the Dashboard>Maxmind GeoIP>Settings page :

Schedule automatic db updates

%PROJECT_NAME comes with 2 jobs :

• Download Maxmind db which will automatically download the latest Maxmind GeoLite 2
• Delete unused Maxmind dbs which will delete all databases but the currently selected

It is advised to update at least once a month the database either using the Databases page or by running 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.

Magic Data integration

Thanks to Johnthefish, this addon comes with 3 Magic Data symbols :

MAXMIND_CITY: Taking the previous result as an IP address, looks up the address in the maxmind database and returns the city name or null. An optional following parameter can be used to request a language by 2-character country code (and if the language is available).

Examples:

• SET '50.28.56.20' AS_IP MAXMIND_CITY will look up the city for concrete5's IP address.
• IP_ADDRESS MAXMIND_CITY fr will look up the city for the current visitors IP address and, if available, return the name in French.

MAXMIND_COUNTRY : Taking the previous result as an IP address, looks up the address in the maxmind database and returns the country name or null. An optional following parameter can be used to request a language by 2-character country code (and if the language is available).

Examples:

• SET '50.28.56.20' AS_IP MAXMIND_COUNTRY will look up the country for concrete5's IP address.
• IP_ADDRESS MAXMIND_COUNTRY fr will look up the country for the current visitors IP address and, if available, return the name in French.

MAXMIND_COUNTRY_CODE : Taking the previous result as an IP address, looks up the address in the maxmind database and returns the country code.

For example: SET '50.28.56.20' AS_IP MAXMIND_COUNTRY_CODE

For Developers

Installing new message themes/layouts

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 js/3rdparty/noty/themes (in your site override). Your themes 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.

You can also create or redefine the provided layouts by adding a file (or copying it) in your site override js/3rdparty/noty/layouts directory.

More information on noty can be found here http://needim.github.io/noty.

Speed up with Maxmind C extension

If you need better lookup performances, Maxmind built a C extension that can be installed to speed up the IP lookup process. To install the extension, please follow their instructions here and there.

Although this addon had been tested with and without the maxminddb C extension installed, the author does not provide free installation and support service for this C extension. If you need support concerning this point, please contact us for a quotation.

Support

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.