Extension Documentation

Chapter 3. Usage
Prev Part I. User Guide Next

Chapter 3. Usage

Table of Contents

Back End Screens
Help Icon
Control Panel
Akeeba Log Synchronisation
Location table compression
Locations
Reasons
Countries
Robots/Web Crawlers
Log Display
Support Tab
Documentation Tab
Component Options
Front End Screens

The administrative back end of the site defines and controls the main storage side of the component. The front end of the site is controlled solely by the use of two supplied modules. A mapper module and the visitor agent module.

This section displays some of the administrative screens available. From the Joomla back end the Components heading will reveal the IP Mapping component. Either select the main title or any of the individually selectable sections.

Back End Screens

There are a number of screens available within the Administration part of the site. These may be presented as tabs within the Control Panel, or accessed directory from the Components drop down menu.

This section looks at each of these in turn and explains their structure and usage.

Help Icon

A number of the back end screens have a ‘help’ icon displayed in the top right hand corner of the screen. Clicking on the icon will invoke a small pop up window as shown below.

Clicking on each of the links will redirect the browser to the appropriate pages on the support website.

Figure 3.1. Help Screen image.

Help Screen image.

Control Panel

The main Control Panel is illustrated in Control Panel. There are a number of separate sections.

  1. The main tabbed headings – Control Panel, Locations, Reasons, etc.

  2. The icons separated into specific types:

    1. Tools – The first two icons provide an alternative entry point to two of the tabbed sections. The third the ‘Akeeba Log Sync` enables the population of IP Mapping locations table to updated from the entries present in the Akeeba Admin Tools Pro log table.

      [Note]Note

      The site has to have Akeeba Admin Tools Pro installed (which is a separately purchased component), otherwise the 'Akeeba Log Sync' icon will not be shown. Any attempt to run the command via a 'backdoor' would also fail.

    2. Updates - This provides an easy check to show that the latest version of the component is installed.

  3. The panel which provides details of the credits etc.

    1. About

    2. Changelog

    3. Credits

Figure 3.2. Control Panel

Control Panel image.

Figure 3.3. About Control Panel Tab.

About Control Panel image.

The ‘About’ panel provides company information. As mentioned the component is provided free, and the user is requested to make a donation if they find it useful upon their site. Users who make a donation tend to obtain preference if they request any enhancements to the product, over those who choose not to do so.

Figure 3.4. Credits Control Panel Tab.

Credits Control Panel image.

The 'Credits' panel displays the details of all the translators who have contributed in providing their efforts in creating language packs for the IP mapping component.

The 'Credits' panel also gratefully acknowledges the work of other people whose previous work we have made use of in creating the component.

Akeeba Log Synchronisation

If the Akeeba Sync Log icon is pressed then there is a series of steps performed in the background.

[Note]Note

This icon is only displayed if Akeeba Admin Tools Pro is installed upon the site. This requires Akeeba Admin Tools Pro to be installed otherwise any attempt to run it will generate an error message and the process will stops.

  1. The entries in the Akeeba Admin Tools Pro Log that are not present in the IP Mapping location table are inserted into the Location table. The ‘ordering’ column in the table is incremented at the same time.

  2. The geolocation details for the entries in the location table are populated initially from the service provided by IPInfoDB and if that is unsuccessful from the Geobytes database.

  3. If configured entries in the Akeeba log older than the specified number of days are deleted from the Akeeba log.

  4. If configured entries in the location table older than the specified number of days are deleted.

  5. The IP Mapping location table is optimised.

The screen below is typical of the display as the actions are performed. The information messages will be dependant upon the stage that the process is performing.

Figure 3.5. Akeeba Log Synchronisation Display

Akeeba Log Synchronisation image.

Location table compression

This features shrinks (compacts) the entries in the Locations table.

Entries (IP addresses) are made into the locations table in an incremental manner. This applies whatever the source of the IP addresses. When entries are removed from the locations table they are removed 'oldest' first, or by specific selection. This means that the record identifiers constantly increase and on a very busy site there is always the possibility of reaching the maximum for the table. There may also be gaps in the record increments. There are two ways in which this can be resolved. The first involves increasing the size of the table field. The second is to provide a means of resetting the table, and it is the second option that has been made implemented in release 1.0.3. The mechanism involves creation of a temporary table and copying existing table entries into the temporary table and then cleaning out (truncate) of the location table before moving of the temporary table entries back into the source table. The final step is to remove the temporary table. Note that the location table entries for the 'visitor' entries are not copied. The reason is that these entries are transient and hence not retained for long periods.

[Note]Note

This feature is often only needed on very busy sites, or where there is a requirement to clean up the table periodically.

The modal window, shown below is displayed when the compaction process completes.

Figure 3.6. Compaction/Shrink Display

Compaction/Shrink Display.

Locations

Figure 3.7. Locations Display

Locations Display image.

The Locations tab is the display of the IP addresses that are candidates to be mapped. A typical display is shown. Clicking on any of the column headings will cause the display to re-order itself.

The icons on the top right hand side perform the expected actions enabling the editing, creation, deletion and publishing of IP Locations.

[Note]Note

Only locations that are ‘published’ are candidates for mapping.

The edit screen is shown below.

Figure 3.8. Location Editor

Location Editor image.

The edit screen is a single screen. Some of the fields are display only. For example the geographical location of the IP address is not editable. Entering or updating an IP address and then saving it will populate the geolocation fields when the record is inserted (or saved) into the database from information obtained from the IPInfoDB service. Some of the data fields may be populated from the Akeeba synchronisation process, IF the product is also installed.

[Important]Important

Audit fields are not editable.

Reasons

Figure 3.9. Reasons display

Reasons display image.

The Reasons display illustrated above shows the known reasons that are associated with the IP addresses in the Location table. It is used to differentiate the location IP addresses so that they may be displayed (mapped) on a separate Google map. Most of the supplied values are those currently used by Akeeba Admin Tools Pro, but the list can be added to as required.

It is not expected that the supplied values will be changed very often if at all. The description field is for informational purposes only and is not used elsewhere currently. This is not a situation expected to change.

Figure 3.10. Reason editor

Reasons editor image.

It is possible to change the defined reasons using the editor. The screen above shows the specific entry for an ‘antispam’ reason. Reasons cannot be deleted however if the reason is associated with any of the IP addresses. Change the reason for the IP address in the location screen and try to delete the reason again.

Countries

Figure 3.11. Countries Display

Countries display image.

The countries list contains all of the currently defined country names and their short (two letter) country codes. This table is used to provide the details for the filters used in the front end modules.

The ability to control the countries allows for the situation where a new country comes into being (or disappears) or where the country codes change. This also provides future expansion were a different IP address resolution service to be used where different country codes may be used. i.e. United Kingdom is using the code GB by some providers.

Figure 3.12. Country editor

Country editor image.

The country edit screen is very simple and enables the entry of a country code and the associated country name.

Robots/Web Crawlers

Figure 3.13. Robots display

Robots display image.

The Robots display illustrated above shows the known robots, also known as web crawlers that may be encountered upon web sites. The information in this table is used to identify visitors to the site that are not individuals but search agents seeking to build up information resources upon other web sites. Typically these robots are used by companies such as Google, Microsoft, Yahoo etc. The site may not wish the visit by these agents to be recorded within the displayed maps. There is an option in the 'visitors agent module' to prohibit this recording and the information upon which agent to exclude is stored in the 'robots' table.

The table enables site administrators to add and otherwise control which agents are within the list of robots to exclude. There are a lot of robots in use on the web and they are being added to all the time. They are also sometimes specific to particular counties, or specific topic, hence it is reasonable to provide this level of control.

Figure 3.14. Robot editor

Robot editor image.

It is possible to add or change any of the specific agents using the editor. The screen above shows one the specific entry for a robot. The only mandatory field is the identifier name, which is the specific string contained within the software (browser) accessing the site. The description, homepage and addresses fields enable the adding of information that may aid in identifying whether the agent should be used in the search list, in the 'visitor agent module. It is likely that future component releases will add, remove or otherwise modify the existing entries. Any entries added by a site administrator will remain unaltered.

Log Display

Figure 3.15. Log Display

Log Display

The log display is used to display the optionally generated messages (component option) from the application. In release 1.2 this is the results of the cron job runs but it usage will be extended with further releases.

Records may be individually deleted or alternatively all the records may be purged from the table.

Support Tab

Figure 3.16. Support Tab Control Panel

Support Control Tab image.

The ‘Support’ tab provides details of how additional information and/or assistance may be obtained on the product. As can be seen Macrotone provide a Frequently Asked Question (FAQ) on the company website, and additionally provide a Forum where users may raise questions.

There is also the ability to raise an issue on the company web site from this panel.

Finally there is the ability to send an email which will be answered as and when circumstances permit. Preference is usually given to forum entries.

Documentation Tab

Figure 3.17. Documentation Tab Control Panel

Documentation Tab image.

There is some basic information about the component provided in the ‘Documentation’ tab, but the user is referred to the Macrotone site for the full documentation for the latest information and recent changes since the product installation.

Component Options

The component itself has a few options which are described below:

Figure 3.18. General Option Settings.

General Options Settings image.

There are a few options available to configure the component. These are all assessed from the ‘Option’ icon in the top right hand side of most of the Administrator screens. Hovering over the option title will display tool tips explaining what the particular option setting does.

One of the options specify the API Key as used to reference the IPInfoDB database to obtain the Geographical location for the given IP addresses/ delete mode. It is necessary to register on the IPInfoDB site to obtain an API key which is then entered into the screen displayed above.

[Note]Note

If the Visitor Agent module is also used on the site then it also requires the API key to enable correct population of the database table. If not explicitly specified in the Module configuration the value specified in the component will be used instead.

The second option is to automatically clean the synchronised entries out of the Akeeba Admin Tools Pro log when the synchronisation process completes. It may or may not, depending upon site policy be desirable to perform this task automatically.

The next option enables the specification of the number of days worth of entries to retain in the Akeeba Log. Any days that are ‘older’ than the number of days specified will be removed from the Akeeba Log. It is recommended to leave at least a days worth of entries in the Akeeba logs.

[Note]Note

If Akeeba Admin Tools Pro is not installed upon the site then the settings of the previous two entries are ignored and are unused.

The last item is the secret key or 'pass phrase' required to run the front end cron tasks. See notes in the 'Cron' section of this manual for more details. The key should be specified as alphanumeric otherwise problems may prevent the cron task from running.

Figure 3.19. List Layout Settings.

List Layout Settings.

There are a number of different fields that can be displayed in the back end locations list display. Not all of these will be of interest to every administrator, so there are options to show only the relevant fields for that specific site.

Figure 3.20. Log Option Settings.

Log Options Settings image.

The log tab currently has two possible options, which control entries in the log table. At release 1.2 the log was only populated by the running of the cron tasks, which displays the information as to how many records are synchronised, updated etc., as currently show in the Sync window if the 'Akeeba Sync icon is clicked.

Later versions have added logging to a number of the other code blocks.

In release 1.2.3 there is a second option to specifically enable the placement of 'debug' messages in the log. It is recommended that this is left off unless requested by the developer, as it can generate a lot of messages which will not be very useful to the majority of administrators.

Prev Up Next
De-installation Home Front End Screens
Go To Top

Joomla! Debug Console

Session

Profile Information

Memory Usage

Database Queries