General Usage
For the first installation, the documentation can be found here.
Using the only API Widget, you can register events that are dispatched by the widget.
The API widget is inserted into the head tag of your theme via the extension. Therefore, it is recommended to access Geolizr through events to ensure that Geolizr has been initialized correctly.
Depending on the logic you want to incorporate, there are different entry points.
You can register an event using the following function:
document.addEventListener
Registers a callback function for a specific event.
document.addEventListener([event], [callback]);
event The event you'd like to listen to.
callback The function that is called whenever the event is dispatched.
Events
Here is a list of currently available events.
geolizr.geoData
<script> document.addEventListener('geolizr.geoData', [callback]); </script>
Callback parameters
geoData An object containing geo-related information:
{ status: [success|false], as: "<provider id ex: ASxxxx Telecom GmbH>", city: "<city ex: Cologne>", country: { code: "<country-code ex: DE>", country": "<country-name ex: Germany>" }, countryCode": "<country-iso-code ex: DE>", isp: "<Internet Service Provider ex: Telekom GmbH>", lat: <latitude ex: 50.9326>, lon: <longitude ex: 6.9342>, org: "<Organisation or Provider ex: Telekom GmbH>", query: "<ip adress ex: 87.78.185.249>", region: "<region-code ex: NW>", regionName: "<region-name: ex: North Rhine-Westphalia>", timezone: "<time-zone ex: Europe/Berlin>", zip: "<zip-code>", currencyCode: "<currency-code>", currency: { code: "<currency-code ex: EUR>" }, countryName: "<country-name ex: Germany>" }
Example
<script> document.addEventListener('geolizr.geoData', (data) => { console.log(data); }); </script>
It is dispatched whenever a notification is displayed.
<script> document.addEventListener('notification.show', [callback]); </script>
Callback parameters
notification The notification:
{ id: [notification id], dismissible: [true|false], rememberCloseState: [true|false], linkText: [text of the link], linkUrl: [URL of the link], message: [notification message], font: [list of fonts], backgroundColor: [background color], textColor: [text color], linkColor: [link color] }
Example
<script> document.addEventListener('notification.show', (notification) => { console.log(notification); }); </script>
<script> document.addEventListener('notification.resize', [callback]); </script>
document.addEventListener('notification.resize', [callback]);
Callback parameters
notification The notification:
{ id: [notification id], dismissible: [true|false], rememberCloseState: [true|false], linkText: [text of the link], linkUrl: [URL of the link], message: [notification message], font: [list of fonts], backgroundColor: [background color], textColor: [text color], linkColor: [link color] }
notification.height The height of the notification.
Example
<script> document.addEventListener('notification.resize', function(notification) { console.log(notification.notification); console.log(notification.height); }); </script>
notification.hide
It is dispatched whenever a notification is hidden.
Callback parameters
notification The notification:
{ id: [notification id], dismissible: [true|false], rememberCloseState: [true|false], linkText: [text of the link], linkUrl: [URL of the link], message: [notification message], font: [list of fonts], backgroundColor: [background color], textColor: [text color], linkColor: [link color] }
Example
<script> document.addEventListener('notification.hide', function(notification) { console.log(notification); }); </script>
It is dispatched whenever a pop-up is displayed.
document.addEventListener('popup.show', [callback]);
Callback parameters
popup The popup:
{ id: [popup id], backgroundColor: [background color], pageBackgroundColor: [page background color], textColor: [text color], dismissible: [true|false], roundCorner: [true|false], rememberCloseState: [true|false], filterlistType: [none|blacklist|whitelist], filterlistUrls: [urls for the filter] }
Example
<script> document.addEventListener('popup.show', function(popup) { console.log(popup); }); </script>
GeolizrAPI.addEventListener('popup.resize', [callback]);
Callback parameters
popup The popup:
{ id: [popup id], backgroundColor: [background color], pageBackgroundColor: [page background color], textColor: [text color], dismissible: [true|false], roundCorner: [true|false], rememberCloseState: [true|false], filterlistType: [none|blacklist|whitelist], filterlistUrls: [urls for the filter] }
Example
<script> document.addEventListener('popup.show', function(popup) { console.log(popup); }); </script>
popup.hide
It is dispatched whenever a notification is hidden.
Callback parameters
popup The popup:
{ id: "[popup id]", backgroundColor: "[background color]", pageBackgroundColor: "[page background color]", textColor: "[text color]", dismissible: "[true|false]", roundCorner: "[true|false]", rememberCloseState: "[true|false]", filterlistType: "[none|blacklist|whitelist]", filterlistUrls: "[urls for the filter]" }
Example
<script> document.addEventListener('popup.show', function(popup) { console.log(popup); }); </script>
Redirects
redirect.executed
It is dispatched whenever the redirects are configured, but blocks the execution.
Callback parameters
redirectResult The result of the redirect.
{ code: [rejected code], message: [rejected Message], redirect: { id: [redirect id], filterlistType: [none|blacklist|whitelist], filerlistUrls: [urls for the filter], redirectIgnoreReferrers: [urls for ignored referrers], redirectUrl: [target URL for the redirect] } }
Codes and Messages
Code | Message / Description |
---|---|
200 | <empty string> / No error - should be executed |
904 | "Filter blocks the Redirect" |
905 | "Referrer ... blocks the redirect" |
906 | "Destination and current URL are the same." |
Example
<script> document.addEventListener('redirect.executed', function(result) { console.log(result); }); </script>
Currency Converter
currency.change
It is dispatched whenever the currency has changed.
Callback parameters
currency The currency code.
Example
<script> document.addEventListener('currency.change', function(currency) { console.log(currency); }); </script>
currency.api
It is dispatched as soon as the currency api is available.
Callback parameters
api.switchCurrency => A function that can be called to switch the currency.
api.getCurrency => A function that returns the currently selected currency.
Example
<script> document.addEventListener('currency.api', function(api) { api.switchCurrency('USD') // switches the currency to USD; console.log(api.getCurrency()); }); </script>