Knowledge Base - Main documentation

Geocode Factory 5

Introduction

Geocode Factory 5 is a mapping component that is compatible with Joomla 3.x only. There is no backward compatibility. For Joomla 1.5 to 2.5 you can use Geocode Factory 3 (Geocode Factory 4 was never released, it was a developer and sandbox version).

Description

Geocode Factory is a mapping component that works with Joomla! core as well as many other 3rd party extensions that store adress and/or coordinates data. It displays joomla content and/or other third party items on maps. You can display multiple marker sets from different 3rd party components on one or more Geocode Factory map if you have the associated gateway plugins installed. Geocode Factory 5 is not a directory or data storage component itself. It is only for mapping geographic data generated by other components like Sobipro, Jomsocial, Community Builder, etc).

intro image

Even without 3rd party components though, you can use Geocode Factory to geocode your Joomla content (articles) and display it on google maps in many different ways. To do this, Geocode Factory 5 uses a gateway and a content plugin (included in your core Geocode Factory 5 package) designed for Joomla articles.

Plugin concept

Geocode Factory starting with version 5 introduces the use of plugins for specific extensions to extend the core component. Each additional plugin will create a gateway between Geocode Factory and that particular third party extension, and will act as a translator between that component and Geocode Factory 5.

By default Geocode Factory 5 is delivered with a gateway and a content plugin for Joomla content allowing you to geocode Joomla articles and display them on maps (gateway plugin) and/or display maps inside articles (content plugin). Other gateway plugins are available to allow Geocode Factory 5 to be used with popular 3rd party extensions such as Sobipro, Community Builder, Jomsocial, etc.

plugin concept

Example : There is a Gateway for Sobipro, that allows Geocode Factory 5 to read geocode data from Sobipro entries and use that data to display makers. After installing the gateway you can create marker sets from your Sobipro data. You can also display many different marker sets on one Geocode Factory 5 map. For example you can show Sobipro entries and Community Builder (or Jomsocial) users on the same map.

Each third party extension has it's own specifications and settings. Some extensions may even have a second plugin available for some specialized and/or advanced feature. For instance, this is the case for Community Builder's profiles extension (the profile plugin).

If the extension you are using is not supported, we may be able to create it via custom development. You can open a support ticket and we'll take it from there.

Documentation

This document will not describe every option of the product. Instead, we have chosen to provide a more practical, tutorial-oriented approach, making it easier to get started. Also, for most options you will see a tool tip when you hover the mouse over a feature that will give you a brief description of what each feature/option is about.

The more advanced and/or complex features are described separately, either here in the documentation, or in their own separate documentation. For example, when we refer to a feature of a Geocode Factory 5 3rd party extension, a different chapter or article is available which will describe the specific options (and tutorial) for these.

Please keep in mind that this is a “living document”. The images and text in this document may change over time because the product is subject to change.

Installation

To install Geocode Factory 5, read the Download, install and update manual.


 

Component Overview

Control panel

What is it ?

The control panel contains several tools described below as well as information about the latest product news, versions and updates, developments, and change log. You access the Geocode Factory control panel from the main menu Component > Geocode Factory.

Control Panel Main

Warnings

You may read here some warnings about your configuration and compatibility.

Updates

Display the list of installed Geocode Factory extensions and available new updated versions. Check the Download, install and update manual for more detailled information.

Main configuration

On the joomla Global Configuration page, you will find a Geocode Factory section where you can control the main component options. These options affect the whole component. You can also access this page from your Geocode Factory 5 main control panel, by clicking on the “Component configuration” link.

Main Configuration


 

Tutorial

Introduction

In this tutorial we will create a map populated with markers and some basic map controls.

The first time you open Geocode Factory you need to confirm some conditions in order to use the product. This message is displayed only once after the installation.

Install message conditions

Map Manager

What is it

Geocode Factory allows you to create an unlimited number of maps, each map having it’s own settings. keep in mind that the maps do not contain any markers. The markers are configured through the use of “markersets” as we will see a little later on in this document.


 

Step 1 - How to create a new Map

The first operation is to obtain a APIkey from Google. You can find more information about this key and obtain it on this page of the google maps api. You need to create a 'Javascript Google maps Api Key'. Once you have your APIkey, simply open the Geocode Factory 'Component configuration' from the control panel, and enter your APIkey in the Google Apikey input.

From th Geocode Factory control panel click on "Create a New Map" or you can go to "Maps Manager" and click on "New" to create a new map.

You'll see the following:

Minimal settings

For the map to work you will need to complete a minimum amount of fields. All mandatory fields are marked by an asterisk (*), but some already have a default value assigned. You will have to give a value to at least the following fields:

On the "Basic Map Settings" tab:
  • Map name: to identify the map, this will not appear in frontend (ex:My Map), this name is used in plugins, markersets, module to identify the map to be displayed.
  • Default center point: This is the pair of coordinates, that will represent the default center of the map. You can enter the coordinate values manually in their proper fields. Or you can simply click on "Load Map" and then select a point on the map that appears or enter an address and click the search button. Select a point by moving the map marker to the desired location using the map controls (zoon in/out) if needed. The coordinate field will then automatically be populated.

pickpoint

On the "Template" tab:
  • Template: by default, Geocode Factory will display a blank page. By using the template system, you will need to define where and what you want to display. The minimal needed setting here is to integrate at least the map placeholder {map} (see the templating article for more details). To do this click the “select” button to bring up the placeholders generator and then click on “{map}” button.

template placeholder selection

Remember that you can use html in the template. Have a look at the sample which is provided under the tab “Sample template”.

You can also use the "Auto-Template" option, by setting it to "Yes". This is the first option found on the "Map Controls" tab of the Map Manager.

Optional settings:

Optionally you may want to configure the various optional map settings available. For each of these options, placing your mouse cursor on the item name will reveal a pop-up explanation of what the field is and/or how to use it.

After you set the minimal and the optional settings, save your new map.

Pattern

What is it

Geocode Factory 5 introduces a new concept named assignment “pattern". A “pattern” defines the relationship between Geocode Factory version and the data to be used from each of the third party extension (Joomla content, Sobipro, Jomsocial, etc). In other words, a pattern will determine which fields of the selected 3rd party extension will be used by GF 5 for the task of “geocoding”.

Specifically, you can create a pattern and select which 3rd party extension fields will be used for determining the address (city, postcode, street, country, etc), and in some cases, which will be used for the coordinates.  Both address and coordinate fields will then be used by Geocode Factory 5 for geocoding the items you wish to place on maps.

You can create multiples patterns for each application. For example you can create a pattern for a primary address and an additional pattern for a secondary address. Depending on the third party extension, you may also use multiple coordinates fields (like in CB).


 

Tutorial Step 2 - Pattern Manager

Default Patterns

When you enter the pattern manager you will see that one default pattern for each installed 3rd party plugin has already been created. This happened automatically when you installed the plugin. For example, in the following image you see a Geocode Factory setup where the joomla content and the community builder plugins have been installed:

Click on the pattern type of your choice to edit/configure the pattern.

On the first tab - “General” - there is nothing that you need to configure  


On the second tab “Pattern Type” the selection has already been made in the case of the default patterns and cannot be edited. It is on the third tab “Assign fields to the values” where the field association is configured.

Assign fields to the values tab

Each third party extension is a little different. The most unique of all is the case of Joomla content where there are no fields to configure (no address nor coordinates). The rest of the third party extensions have some fields to configure.

Below is an example from the Community Builder pattern type field association. You can see the Community Builder fields which have been chosen to be used for each case (both coordinate and address fields scenario).

As you can see, to define the address you are able to select a lot of information (city, postcode, street,county, state, country). There is no need to select all of them. However having too few selected may give a less accurate geocoding result.

For example, if you only select the city, then the marker will be placed on the city position. If you also select the street field which also has a street number in it’s data, then the marker will be placed on a more exact position.

Note: Usually only the "text" fields appear as options in the selectors. In the GF main configuration, you can allow the application to use all type of fields, but this is not recommended, so use this at your own risk.

Save your pattern when you’re finished selecting the fields.

New Patterns

As we mentioned earlier, you can create multiples patterns for each application. For several extensions it may be useful to have these different patterns. For example, in Community Builder you can have multiples addresses for your profiles (ex: office and home address). Or in Sobipro, you may have two different sections with different type of entries (ex: restaurants and hotels). In these cases you can create one pattern for each target (each address type in CB or each section in Sobipro) and so each pattern will contain it’s own coordinates and/or address fields. Finally, in your markerset (or geocode tool) you simply need to select the right pattern to be used in each case.

To create another pattern, click on the new button on the top left hand of the Pattern Manager. On the first tab you need to give your pattern a name.

On the second tab you would have to select the pattern type and save to get the third tab “Assign fields to the values” to appear. For directions see the “Assign fields to the values” section above.

Markerset manager

What is it

A markerset contains the rules used to display markers. You can add multiple markersets to one map and each markerset may also be applied to multiple maps. Each markerset has it’s own settings. On the same map you can have markers from multiple sources, with different settings (marker icons, bubble template, etc). This makes GF a very powerful and highly customisable Joomla extension.


 

Tutorial Step 3 - How to create a new markerset

From the GF control panel click on "Create a New Markerset" or you can go to "Markersets Manager" and click on "New" to create a new markerset.

On the “Basic Markerset Settings” tab:

  • Markerset name: Enter the name of the markerset
  • Map selector: Click to select the map you want this markerset to be displayed on. In other words, choose a map that you have created previously in the “Map manager”  for ex: “My Map”.

On the “Template ” tab:

Here you can determine the contents of the bubble template of the markers on the map and also the sidelist template (if you choose to use them). In other words you can define where and what you want to display in each case.

How bubble work

When a user clicks on a marker a bubble is loaded. This bubble is loaded dynamically when it's clicked, and is not included into the page HTML code. The content of this bubble is defined in each markerset for all markers loaded by this markerset.

The set of parameters and how they are displayed is called a "bubble template" or "side template" for sidelist. You can edit this template on the markerset editor page.

Placeholders concept

In Geocode Factory, markers are linked to entries, events or profiles. Bubbles can contain HTML code, and placeholders. Geocode Factory offer the opportunity to use placeholders to represent the corresponding value from that data source. Placeholders are always between brackets { }. Placeholders are based on supported fields that are available and vary depending on the current component the makerset is using as the data source.

To see the current list of place holders, click the “select” button to bring up the placeholders generator tab. You can click on the elements you want to add in each case and you can include html. You will find some sample templates under the tabs “Sample template” and “Sample tabbed template” that you can use.

This mean that if you write <h1>{title}</h1> into your template, the result will be the entry title (or profile name) into a title 1 style (of your joomla! template) like "Entry title". 

 There is a lot of placeholder, each depending the current gateway (pattern), you will see each time a little help how to use it.

On the “Markerset type ” tab:

Select the markerset type from the dropdown. The selection depends on which 3rd party items you wish to display with this markerset (joomla content, community builder, sobipro, etc).

Other optional settings:

You may want to configure the various optional markerset settings available as well. For each of these options, placing your mouse cursor on the item name will reveal a pop-up explanation of what the field is and/or how to use it.

Marker icons

There are many different options by which to define the marker icons :

  • Google: This is the standard default google icon.
  • Uploaded image: Here you can use any kind of image you have uploaded in the joomla image folder. The image should be a transparent png.
  • Mapicon: A selection of the mapicon from mapicons.com
  • Avatar/entry: This will use the current marker’s source image. For profile-based markersets it will be the user’s avatar, and for directory-based ones, the entry logo. You can also set a custom size to have the same icon size for all icons. A background icon (half circle) is used to define the center point of the avatar icon.
  • Folder icon: For directory-based markersets, the image/logo of the category the entry is located in will be used (if the entry is in multiple categories the first one will be used by default).

You can define a fixed size for the marker icons, there is 2 methods:

  • Fixed size: You need to enter a with and height, integer values in px. All images will have the same size. Sample: [16] and [16], aéé images will have this size.
  • Factor size: You need to enter a integer values in % into the first inputbox (you see the % unit). This factor will be applied to all images. Sample: [33] -> a 60*90 image will be displayed as 20*30
The specific settings tab

This tab is generated depending on the currently selected pattern. The settings are different for a profile component based pattern versus a directory based component one.
Here you can generate the fields based on your choice of filter for the current markerset (like field_color=’red’). Again, the filter here depends on each third party application you are currently editing in the markerset section. If you use the filter generator (where you select the field, the operator and the tested value), a little contextual explanation is displayed in each case, with a little sample as well.
The use of this feature is the most common source of errors that result in no markerset displaying! Remember that here you are adding a clause/condition affecting the mysql database query. Each wrong or missing charter/quote will cause an error. Handle with care!


 

Geocoding

What is it

To display any type of content (items) on a map, or to be able to search these with a radius search tool, the content items need to have coordinates. The task of assigning coordinates to items (entries, user profiles,etc) is called “geocoding”.

Overview

Several third party extensions already have coordinate fields ready to be used for mapping purposes. The data in these fields is usually populated during the creation of the entries in each respective extension. In cases where they don’t have this data available, GF has a feature called “Batch geocoding” where the address related fields of the 3rd party extensions are used to get the coordinates that are needed for mapping. Have a look at this table for examples of some of these.

Product

Frontend

Backend

Note

 Joomla content plugin

 during article creation

 

Built in geocode or

 

Geocode Factory batch geocode

 

 Sobipro

during entry creation*

Geocode Factory batch geocode

* optional Sigsiu’s plugin (SP-GeoField)

 Mosets Tree

during entry creation

Built in geocode or

Geocode Factory batch geocode

 

 Community Builder

during profile registration through Geocode Factory profile plugin

Geocode Factory batch geocode

 

 Jomsocial

during profile registration through built in function

Geocode Factory batch geocode

 

Batch Geocoding

What is it?

Batch Geocoding is an operation which geocodes multiple entries in one take. In other words, batch geocoding is the execution of a series of geocoding tasks on your computer without manual (human) intervention.

Keep in mind that Google limits the number of geocode requests to 2500 per 24 hours and per IP. Using a google api key will not change this quota.

Note: If you are using shared hosting (like OVH), the quota is shared between all account that share this IP. Our advice is to use a good Joomla hosting company.

Overview

To geocode entries or profiles from the backend you need to select the third party extension you want to geocode and the pattern to use. Once the entries appear you can start to batch geocode them.

Note: You can also geocode each entry separately, or just check the address (see "Manual Geocode" section below).


 

Tutorial Step 4 : Batch Geocoding

From the Geocode Factory control panel, or your left hand Geocode Factory menu, click on "Batch Geocoding".

First, you must select the desired extension from the supported extension dropdown In this example we will select the “Community Builder”extension as seen in the image below.

Secondly, select the desired pattern for this extension from the second dropdown. In the image below, only the “Default - Community Builder” pattern exists.

You will then see the list of Community Builder profiles you have in your joomla site like the following image.

You now have three options:

a) Geocode Filtered

You can geocode all the CB profiles in one take using the “Geocode Filtered” button located at the top left part of your screen. In this case, Geocode Factory will process all of the addresses/locations of your CB profiles in one batch. Ideally, you would use this scenario when all your entries are missing coordinate data.

Note: You may use the search box tool on the top of the screen to filter out the articles that are listed (this tool will search in the title of your profiles). Similarly you can use the dropdown next to the search to filter the list between the articles that have coordinates and those that don’t. Theoretically you would want to select the entries that don’t have coordinates in this case.

Once the process is finished click on the “Geocoding job done” button, as seen on the image below.

b) Geocode Selected

This is similar to the above step. In this case you can geocode many CB profiles in one take by selecting the CB profiles you wish to geocode first and then clicking on the “Geocode Selected” button located at the top left part of your screen. To select the profiles, tick the check box of the  CB profiles you want to geocode. The check box is located on the left of each listed CB profile. Geocode Factory will then process the addresses/locations of the selected profiles in one batch.

This option may be especially useful if you want to edit the address/location of a few profiles.

At the end of the Geocode Filtered or the Geocode Selected processes you should get a screen that looks like this:

Finally, click on the “Geocoding job done” button once the process is finished, as seen on the image above.

c) Manual Geocode

Alternatively, you can geocode the CB profiles manually (one by one). This option is also very useful if you want to correct or generate (geocode) the address/location coordinates of one or a few profiles. For example, you can use the dropdown next to the search to filter the list and display only the entries.items that don’t have coordinates.

To geocode the profiles manually first click on the “Load address” button next to the article you want to geocode to verify it is correctly being generated. The address/location will then appear under this button.

Once the address has appeared and it looks correct, proceed by clicking on the “Geocode this item” button that stands above the map area. Clicking on this will geocode the address and you should see a message appear under the map like this:


 

Publishing a map 

The final step is to publish your map. You can do this in two ways: As a core joomla component page, or as a joomla module.

Tutorial Step 5

a) Publish map as component:

In this case the map is displayed as page content (as joomla main content).

Create a new joomla menu item inside the menu of your choice (ex:”Main menu”).

As the “Menu Item Type”, select “Geocode Factory 5” and then “Maps and markersets”

Next, add a Menu Title (ex:”My map”) and select the map you want to display (ex:”My map”). The options you have here are taken from the list of maps found in your GF “maps manager”. In the following image there is only one option available.

Finally save your new menu item.

b) Publish map as module:

The map module is very useful for displaying a map at same time with another component. The typical example is to display the map next to a directory component, and to set the related markerset with the auto-category feature enabled. In this case, the markers that will be displayed will be entries belonging to the categories you are currently browsing only (and child categories as well).

Another example is to publish the module on a detailed page view, of either a directory entry or a user’s profile. In this case, the module will display the currently viewed marker for this item (or markers if the entry/user has multiple addresses).

Zoom

The module zoom is based on the map settings or can be forced by the module. This is especially useful when the module is used for the detailed view context where you can select the level you prefer..

Show/hide depending on context

The maps can be hidden in several situations. The typical example is when you use two different maps in a directory component:

  • a) The first map used for the “auto-category” context of a directory as discussed above. The map here displays the markers depending on the categories one is browsing (category view of the component).
  • b) And another map on the current entry view (the details view) where we want to load a different type of map (for example, satellite view) with different markersets (ex: loading only the current marker and the 5 closest markers in a given radius).

In this case you need to display 2 different occurrences of the module in different component views (category and details views respectively). But both modules are published on the same page (the directory component menu link). So you need to define more advanced settings to hide or show the map depending on the view in this case. You can work with the url parameters, and define the behaviour of the module in each case based on the component tasks. So to hide the first map in details view of the component, you add “task=viewdetail”. 


 

Advanced Features

Import tool

What is it

The import tool is designed to import old maps and markersets from Geocode Factory 3.x. The old tables (from Geocode Factory 3) can be in the current database used for Joomla 3 or in another database.

How to import

In the case where the old database tables are in a separate datatabase, you need to enter the correct database credentials in the Geocode Factory settings (Main Configuration discussed above) before proceeding with the import. The “Import” tab in the main configuration looks like this:

Import Settings

The first option “Imported map/markerset prefix” is the extra prefix that will be applied to the old tables once they are imported into your current website’s database. The rest of the options are pretty straightforward. They refer to the database where the old tables are to be found.

Creating a temporary readonly database user, and removing these credentials from the settings after importing is a good idea. Another good practice is to do a backup before import.

When the correct database credentials are in place, clicking on “Import old” from the Geocode Factory control panel will give you the list of maps and related marker sets available for import. You may select the ones you wish to import and then click on “Import the old maps, with the attached markersets” on the top left corner of your screen to proceed (see image below).

Import Tables

Keep in mind that there is a big difference between Geocode Factory 3 and Geocode Factory 5, the new version does not work in the same way as the old version. For example, the pattern concept (see next section) is a new development in the Geocode Factory 5 version only. The default pattern will be used for imported data in this case. The database structure is very different as well, so some settings cannot be restored from the old tables.

Overall, the import tool will help you restore the same maps and markersets as the ones in your old configuration or installation, and it will save you a lot of time. But you need to check the integrity of each imported item.

 

Applies To

Geocode Factory 5