Knowledge Base - Getting Started Guide

Get Geocode Factory

Welcome to this getting started guide for Geocode Factory. Here you will find our official Geocode Factory getting started guide. Please read this introduction before you start.

There is different subscriptions plans, with or without support. You can also update your subscription to a plan with support. And different options. The main options are :

  • Component only: contains Geocode Factory and all needed modules an plugins to work with the supported third party extensions
  • with CB map search: allows you to display the CB lists feature search results on maps.
  • with SP map search: allows you to display the Sobipro search results on maps.

Installation

Introduction

Geocode Factory is a standalone component, but since it's main purpose is to map data created by 3rd party components you need those components as well as Geocode Factory. In some cases there you will also need to install other extensions for Geocode Factory (plugins, third party plugins, and modules). This chapter will guide you in this process. Please read each article of this section, we will explain each case.

Download

The first step to do is download the Geocode Factory component from My Susbscriptions page. Depending your subscription you will see one or more folders, and in each folder a list of files to download.

List of main files

The folders contains the following files / products :

  • Geocode Factory : contains the Geocode Factory component
  • Community Builder profile plugin : This is the plugin to be used with Community Builder. It is installed automatically in CB. Follow the detailed article about plugin configuration.
  • Jomsocial profile plugin : includes the plugin to be used with Jomsocial. Follow the detailed article about plugin installation
  • Article plugin: display maps in articles
  • Show Map module : allows you to display a map in any module position.
  • Dataform module : allows you to display a map in any module position.

Installation

The installation is 100% automated. All component, modules, and plugins (including the Community Builder and Jomsocial plugins) are installed at the same time in one unique operation. All theses files are into the main component file, and also available separatly (in the extra folder).

  • First do a backup of your site, as is good practice for any new extension installation/upgrade.
  • Download the package file : geocode_factory_3-x-x-xx.zip
  • This file must be installed, using the Joomla! installer.

The component, modules and all plugins (including for CB) are installed automatically.

Update

When you download a new version, simply install it over the old, by following the installation procedure describe above. All realted products will be updated and settings will be preserved. You don't need to uninstall the previous version.

Important : don't forget to make a backup of your site before installing any extension!

Geocode-Factory-how-to-install

 


Component configuration

At this point, you should have installed all needed products. Now is time to configure the installed extensions.

First time we will setup Geocode Factory for basic usage. You will find advanced configurations in the later "Advanced features" chapter.


Basic settings

Control panel

When you open the component, you will see the control panel (cpanel). The control panel, contains 2 main areas :

  • the icons area on the left
  • the info panels on the right

geocode-factory-control-panel

Version and registration

You need to register the product with your order number to enable the version check and support. Follow this procedure within the right info panel under the "product registration.." section :

  • Enter your order number,recevied by email after your Subscription is validate
  • Click save button

Note : in some case if you use a special backend template, the save button won't work. In this case simple switch to normal template, for registering.

gf

The next panel is for version checking. It checks with the MyJoom website to see if you have the latest published version. A message appears if an update is needed. In some cases the available version is lower that the installed version, because not all intermediate versions require an update.

 

configGeneral settings

gf_23_lines_03

Find here the description of several settings (dont forget to use the tool tips to learn more) :

  • Google server : National server which will be performed the geocoding queries. If the majority of your users are in France, enter google.fr. Leave google.com if your site is international or if you are not sure.
  • Profiles by passes : When geocoding, if the planned job is, for example, geocoding of 500 profiles, the runtime breaks down this number in smaller groups in order to not overload the server and avoid unpleasant messages like 'Time out'. If you choose 50, the program completed 10 passes in our example (10x50 = 500).
  • Server break : Sets the discharging pause in seconds between server passes.
  • Use all field type : in set to yes, all fields are used in select box (backend). For example you can use the field type ‘Country’ in CB. At your own risks, because we cannot test each type of custom field.
  • Line colors : define the link line color between markers.
  • Waysearch button : draw a button that allows Geocode Factory to locate the user's current position (browser location), into the bubble route form.
  • Debug mode : see the article ‘using the Geocode Factory debug mode
  • JQuery options : can be changed if your bubble tabs are not properly loaded. You can use the no-conflict mode or use your own library (loaded by another component or the template). In some cases the usage of the "jQuery Easy" plugin has solved some issue if you don't find another solution.
  • Radius circle color : You can control the color of the radius circle. You can enter a color like ‘blue’ or a color code like ‘#00A1FF’. Note this color corresponds to the border of the circle and the circle “fill” is based on the same color, but translucent.
  • Sales area color : Same as before, but for the sales area circles.

Basic map configuration

Introduction

In this chapter you will find some information on how to create a basic map. To learn more advanced features, please got the the Geocode Factory Concepts chapter of the documentation.

Map managercarte

The map manager allows you to create Google maps. This is where the options are set to display them.

gf2

Note : the map ID (before Joomla 1.6, this needed to be set manually in the modules, or menus) is visible in the map list shown above.

When you create a map, you see a form that contains different tabs. Below the tabs, you will see the resulting map. To create a working map, you  need to set several options (some are already set to default), see bellow the main settings :

  • Name : This is a name of the map
  • Width/Height : Value in or % pixels defining the size of the map.
  • Template : Represents the design around the map, and where you place the map. For now, write [map] in this textarea (you will find more info about map templates in the Advanced map template chapter in advanced Geocode Factory features article)
    tuto_map_settings
  • Published : Allows you to set whether the map is published or not.
  • Duplicate markers : if you use any markerset selector, this option need to be set to 'All', see the 'Working with directories and categories' chapter in the Geocode Factory advanced features article to understand this concept.
  • Number of markers : Limit the number of marker on the map. Set to "0" to show all.
  • Latitude and longitude center : Sets the default center of the map. You can choose this value by picking a point on the example map. It's strongly advised to select a default coordinates, event if you use another method to center the map, then in case of problem, the user will at least land where you have selected.
  • Center on : Sets the center of the map on the current registered user, fixed point, all markers or the browser location. The 'browser location' option require that the end user allow this with his browser. If not, the map is centered on the default coordinates.
  • Google Options : These options interact directly on the design of the map. You simply apply the changes to see the result on the sample map.
  • Zoom range : Sets the zoom range level, for the maximum and minimum zoom level.
  • Cluster : Activate and set the parameters for clustering. Clustering groups markers that are near each other to clean up the map display. See the clustering with Geocode Factory chapter in the Geocode Factory advanced features.
  • Show lines between my addresses : if you allow multiple address per profile you can connect the different user’s address (home / office / …) with a line see How multi address work.
  • KML: here you set some KML, KMZ and/or geoRSS url separated by commas ',' and starting with http://.
  • Cache duration : See how to use the cache in the Google maps chapter to understand how this work.
  • Different map type / tiles : see the how to use openstreet map or other map types detailled article.
  • Use tabs : see the detailled article about Google map bubble templating
  • Use gallery : see the detailled article about Google map bubble templating.
  • Bubble and radius actions : Select the desired mouse interactions, as example, you can open the bubble with right mous button, or do not allow bubbles.
  • Radius : see How the radius settings work.
  • Select the layers to load : This option allows you to select what additional layers you can load on your map. It’s possible to load the cycle, traffic, transit, weather (°C/°F) and clouds. You can load multiples layers at once. Note: the clouds are only vsibible at high zoom levels.
  • Map style in JSON format : This is an area where you can customize the “Style” of a Google map. You can read more about this here: styling page. With this option you can customize your map, add styling options like water areas, simple roads or a country limit, etc. It can be fine tuned for color, width and other things! Simply click on the style wizard link (style wizard) provided into the label area, and build your styles. When your are ready, on the bottom of the style list, click the “JSON preview” button, then copy-past the result in the textarea for this option.
  • Mouse behavior :select what mouse actions have what behavior. For example you can define that the sales area circle is displayed when the mouse flies over the marker or open the marker bubble when you right click on the marker... These are the main options :
    • Bubble opening : defines how you want to open the markers bubble
    • Circle center : defines how to to set the radius circle center
    • Sales area : defines how to draw the sales area (see the radius article)
    • GPS Track : defines how to draw the GPS tracks
    • Zoom on tracks : specific to GPS Tools markers. When any track/route is displayed (after clicking on the marker, fly over, ...), the map is zoomed to show the whole track.
  • Country limiter : This is used for the fronted radius search form, where the user can type any location and select a radius, and the maps zoom and load only the markers in this area. With this option you can filter the prediction (autocompletion) of places in one defined country. Simply enter here the ISO 3186 country code in 2 digits (us = USA, fr = France, ...).
  • Prediction type : Allows you to select between 3 different types of autocompletion prediction in the frontend radius search : “All”, “Cities” or “Business”. 

Field assignment

paramsField assignment

On the control panel, depending the installed third party extensions you find a list of links to assign the fields. If you don't find the link for your extension, this is due one the following reasons :

  • the extension has a fixed list of fields
  • the extension doesn't allow geocoding

geocode-factory-assign-menu

Geocode Factory need to know what field is used for what info (field_city is the city...). The more fields you select the more accurate the geocoded location is. Of course you can also select only one field, for a geocode based only on postcode or city. The list of available fields and available list of choice is depending the third party extension you are using.

gf4

The lat and long fields are very important, because these fields will receive the coordinates. In some extensions  like Jomsocial, Mosets Tree and such, theses fields are include in the core, then simply leave the 'Use internal fields' option. Of course you can use your own created custom fields.

Note : there is no importance if you set the field_city in the front of country, or such, the names are defined for ease the reading only.


Batch geocodinggeocode

Geocoding is the process of finding associated geographic coordinates (often expressed as latitude and longitude) from other geographic data, such as street addresses, or ZIP codes (postal codes).

Batch geocoding is the idea that you can take all entries/profiles in a given component and set geographic coordinates for all entries/profiles in one unique operation. In the Geocode Factory control panel, depending the installed extensions, you find a "Geocode" link for each third party extensions in which you can geocode the related entries/profiles. If you don't find the link for your extension, this is due one the following reasons :

  • this extension includes its own Batch Geocode function
  • this extension doesn't allow geocoding

geocode-factory-geocode-menu

 

You are now ready to Geocode your data. If you have users or entries created without coordinates use the geocode icon in the right section (if available) : Community builder section, Jomsocial section, …

gf5

On the Geocode page, you will see a list of the items you can geocode. The displayed address and coordinates are dependent on the component 'field assignation'. You can control the items displayed on this list with different filter depending the context (CB users, Sobipro entries, …). There are 2 different action buttons :

  • Geocode selected : will geocode only the checked items
  • Geocode filtered : will geocode only the items that correspond to the current filters (through all pages of results if more than one page exists).

The geocode processes a group of items at a time. The size of this group was set as an option in the component parameters. You can see how many profile are left during the process.

gf7

Note : at this day you can Geocode 2500 entries by 24h period (even with an apikey). This is a Google limitation. There is a detailled article in the Geocode Factory Faq.


Basic Markerset configuration

Introduction

In this chapter we will explain how to populate your Geocode Factory maps. Geocode Factory uses markersets. A markerset is a kind of filter that retrieves information from a data source. A basic markerset will return all markers from a component and as you add additional configuration settings you can finely control what is displayed. In other words, a markerset is used to create the rules to load the markers on the map.

A markerset will generate markers, and each marker represents one user’s profile, one directory’s entry or one event. You can load multiples markersets on one map. Even if the source of the markerset is the same extension. For example you can create 2 markersets from your Community : one for women with a pink icon, and a second for men, with a blue icon (of course you need to have this information contained in the user's profile).

To learn more advanced features, please go to the the Geocode Factory Concepts chapters of the documentation.

Markerset Manager lists

By clicking the markerset icon in the Geocode Factory control panel, you will be taken a list that contains all available markersets. You can filter this list by extension, map and name. To create a new markerset, simply click the add button corresponding the desired extensions (the button depends the Joomla version, in the capture below is the green icons).

markerset list filters

 

You can easily edit, duplicate or delete a markerset, by clicking the corresponding button in the Edit tools column. You will see the icon you have assigned to the markerset into the Marker icon column, and if you use the user avatar as icon you will see here a generic avatar. This is the same for the category icon, you will see a category logo.

 

tuto_markerset

The creation of a markerset is very similar between the different supported extensions (Jomsocial, Sobipro, Adsmanager, …). The most important difference is between a Profile markerset and a directory markerset. Here are the common settings for all of them :

  • Set name : Name of the set, used in frontend for the different lists
  • Map : Sets the map on which the markersets are displayed.
  • Marker Accuracy : Applies to the marker position during the display. You can reduce the accuracy if you don't want to display exact locations. The coordinates in the source profile will not be altered.
  • - High : the marker keep coordinates as is when displayed on the map
  • - Medium : the marker is randomly moved with a distance of about 100m
  • - Low : the marker is randomly moved with a distance of about 500m
  • Menu itemid : joomla menu item id that defines the context to see the detailed view linked from the bubble. See here how to use menu itemid.
  • Bubble width : define bubble width, see width of the bubble.
  • Field for title : Select the text shown on the marker tooltip and the [TITLE] placeholder
  • Marker image : The image must be in images/stories, ideally in png (IE dont understand gif on maps). See the marker images article.
  • Avatar size factor : Apply a custom size to marker icon
  • HTML code snippet for the bubble : this is the template of the bubble. You can use HTML tags, CSS styles, and js code mixed with the placeholders variables. The available variables are listed on the google maps bubble templating article. You see that many of the fields of the used component (CB/JS/SOBI) are supported. The [field_city] will be replaced by the current profile city. Example: London. In addition to these fields, you find some others special placeholders like [LINK], [ONLINE_STATUS], ... theses are component dependent and are replaced by the profile value.
  • Placeholders texts : Click the insert button to copy the variable into the template box above
  • Filters : This allow you to filter the markers by filters with logical conditions. Like field_age > 18, or such. Depending the component you are using you will be able to create simple to elaborate filters. There is an FAQ article that provide examples : see the filters creation chapter.
  • Radius : You can enter here a value (in kilometers or miles) to search profiles (Community Builder / Jomsocial / Sobipro, etc) in a radius around the logged user or from a fixed point. See How radius search works
  • Users to Allow : Joomla user groups you give access right to see the markers (users that have access)
  • Sales area radius : select the field where you have stored the sales radius distance of each entry. This field need to contains a numeric value. Please read the radius article to learn more about this feature.

Markerset for profile components

  • Show only logged in members : the markerset searches only the currently online members
  • Online / offline template : replacement code snippet that contain a text that shows 'Online' or 'Offline', you can customize this value by adding some style (green/red color, ...) or including a logo. See the bubble templating article under user online status.
  • Groups to include : Joomla user groups to include in the field (users that are displayed)

Markerset for directory components

  • Categories : you can select the categories to include here. See the working with category article.
  • Section (sobipro only) : Sobipro allows to create different fields, entry forms, detail depending the section. Before the fields are displayed in listboxes, please select a section, and save the markerset. The remainder of the options will then be available.
  • Draw lines : draw a line between the entry marker and the marker of that entry's owner.
  • Autocategories : if you publish the map through the Geocode Factory module, and this module is published on a directory component you will see only the entry of the current category. See the working with category article.

Markersets filters

Basic filters

When you generate your markersets, you can use built in filters to further refine the displayed markers. For example :

  • Logged in users vs not logged users
  • Users from a particular access level
  • Entries from a specified category or group of category
  • ...

The built in filters are dependent on the current extension (CB, Sobi, ...) selected when you created the markerset.

Custom filters

In some cases you will be filtering your data by different custom fields. Each extension (CB, Sobi, ...) used to build the markerset has its own database structure and its own method of filter creation. There are controls to generate the filter query (field choice, operator choice, and condition). Note : in some case there is 2 query generators like in Sobipro.

geocode factory filter query generator

Bellow is a list of sample queries you can adapt following your needs. Note : only the bold text is replaced by your query filter, all other are the Geocode Factory regular internal queries, and don't reflect the exact code (it's just the query syntax).

You also could debug the filters following this procedure :

  • Enable the debug mode (see the how to use debug mode article)
  • Reload the map
  • You should now see a link over the XML file
  • Open this link in a new window
  • Now you should see more info about your error
  • If you cannot find the problem, please send us the debug output.

Filters for specific components

Filters for Community Builder

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT values FROM table WHERE conditions AND your_filter_here AND conditions

Regarding the CB database structure you can chain the different values using AND or OR operator : ((cb_field_2 = value) AND (cb_field_2 = value))

Filters for Jomsocial

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT user_id FROM table_fields WHERE your_filter_here

Regarding the Jomsocial database structure you cannot chain the different values.

Filters for Adsmanager

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT values FROM table WHERE internal_conditions AND your_filter_here

Regarding the Adsmanager database structure you can chain the different values using AND or OR operator : ((field_2 = value) AND (field_2 = value))

Filters for Sobipro

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT entries FROM table_fields WHERE your_filter_here

Regarding the Sobipro database structure you cannot chain the different values.

Filters for Sobi2

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT entries FROM table_fields WHERE your_filter_here

Regarding the Sobi2 database structure you cannot chain the different values.

Filters for Mosets Tree

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT values FROM table WHERE your_filter_here

Regarding the Mosets Tree database structure you can chain the different values using AND or OR operator for the base fields, and add a v. for the other fields : ((field_2 = value) AND (field_2 = value))

Filters for Jomsocial Event

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT entries  FROM fields WHERE  your_filter_here

Regarding the JS Events database structure you can chain the different values from the events using AND or OR operator : (( field_2 = value) AND ( field_2 = value))

Filters for JEvents

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT events FROM table WHERE your_filter_here

Regarding the JEvents database structure you can chain the different values using AND or OR operator : (( field_2 = value) AND ( field_2 = value))

Filters for Joomla contents

To understand how the filter is applied, see where and how the condition is added to the markerset query :

  • SELECT articles FROM table WHERE your_filter_here

Regarding the Joomla database structure you can chain the different values using AND or OR operator : ((field_2 = value) AND (field_2 = value))

Advanced custom filters

For advanced stuff, and for advanced samples, read the Specific extensions help chapter, there is several cases where we have helped customers for the filter creation.


Publishing maps

There are multiple methods by which you can publish a Geocode Factory map, you have multiple choices :

  • Create a Joomla! menu item pointing to a specific map
  • Publish it through the Gecoode Factory map module
  • Show a map within a content article
  • Show a map within a user's profile (Jomsocial/Community Builder)

Publish a map through Joomla! menu

This will display the map as main content of the page.

  • In Joomla! backend > create a new menu item
  • Select the Geocode Factory type
  • Select one of the choice :
    • Map based : you need to select the map, and all linked markersets will be load
    • Markerset based : you need to select a markerset, and the linked map will automatically loaded. Note: you need to know the ID number of the markerset before you can create this type of map. This is found in the Geocode Factory, markerset control panel.
    • select-geocode-factory-menu-joomla
  • Save the menu item

On the front-end you will now see a new menu item linking to the selected map.

Publish a map using the Geocode Factory Show map module

You need to have the Geocode Factory module installed.

  • Select the module manager
  • Click the new module, and select the Geocode Factory module type
  • Select the map to display
  • Publish the map on the needed page

tuto module

All map settings are defined in the Geocode Factory map manager, but, you can force the zoom level here (leave empty or 0 to use the map zoom).

Find more detailled info in the how to configure the module article.

Publish a map within an article

There are 2 ways to display a map in an article. Both work with a Joomla! content plugin.

Loadposition method

  • Create a module based on the Geocode Factory mod_gf_showmap module
  • Publish the module into a position of your template, or a custom position that doesn't exist
  • Publish the Content - Load module plugin. This is a core plugin of Joomla!.

map-art-006

  • Edit the article where the map should appear by adding the {loadposition position_name} in the text, where position name is the position where the module is published

map-art-003

  • The resulting article show the map into the article.

map-art-002

  • You can embed the {} in a div position and set the float property, to align the map into the text.

map-art-004

  • Of course you can play with the styles as well and add some decoration like borders and such.

map-art-005

Article Plugin

Since Geocode Factory v3+, you can install the 'Geocode Factory Article plugin', that allow also to display a map into an article. The plugin need to be installed and published, and you need to set the plugin code into the article {myjoom_gf xxx}, where the xxx is the address where the map will be centered.

Publish a map within a user's profies

This method can only be used if you use the Community Builder or Jomsocial profile plugin provided by Geocode Factory. Please check the profiles plugins related article on this site to have more details.


Map Module Configuration

Introduction

There are multiples module that are installed by default with Geocode Factory. This is how they work :

Geocode Factory Show Map

Configuration

Before you configure the module, please ensure you have already a map and at least one markerset created in Geocode Factory. Please refer to the Geocode Factory component documentation for this.

In the Joomla! module manager edit the newly installed ‘Geocode Factory’ module. Publish the module on the pages where you want to display it and set required parameters :

  • Select the map to display in the select list (in Joomla! 1.5, you need to enter the map ID manually)
  • Select any Joomla! tasks where you don't want to display the map (see below how this works)

tuto_module

There are no parameters to set for the map itself as all map-specific setting are in Geocode Factory component. However, you do have the option to force the zoom level and override the component settings to be sure you have the desired zoom in your module context.

The module can interact with some other extensions :

  • All supported 3th party directory extensions (Sobipro, Mosets tree, AdsManager, …). Refer to the dedicated article How Geocode Factory works with directories categories.
  • Sobipro Map Search plugin to display the search results on the map
  • Community Builder Map Search plugin to display the search results on the map
  • Radius Search Application for Sobipro

Tasks To Hide Module settings

You can hide the module in some cases, like in detail view of Directory page. This is easier to explain by example : we want to hide the module in the search page of Sobipro, and show it in the search results page. Set the back-end parameter to include at least :

gf_module_task01

In the search form, the module is not visible :

gf_module_task02

And in the search result page, the module is visible.

gf_module_task03

Note : for this example, we have used the Sobipro search result map plugin in addition to the module.

If you want to hide the map but you don't know the value of the URL parameter that is used, then use this place holder : ? Sample : catid=? will hide the map, each time catid contain a value.

Warning, if you remove all default tasks from the list, then the module will reset to default value (all default detail tasks). To prevent this, simply set a fake value, like '0' or 'nothing=nothing'. There must be something in that field.

Geocode Factory - Data form

This module allows you to display map control in any module position  and to display a radius search form on any page of your site even WITHOUT the map being displayed on that page. This radius search will search through the map markers of the current configured map.

The main parameter of this module is the "Map page url". You need to provide the URL of the page where the map is published (the map where you need to do the radius search. The path needs to start with "http://", and a non-SEF URL is recommended.

The other parameters are related to the needed controls of the page, like the sidelist, the radius values, etc.

A requirement to use this feature is to have the [radius_form] placeholder present on the map page. Please read the advanced map template article for more detail.

Here is an example: In this first page, there are no maps, just the radius search, simply enter Irvi... and the auto complete will suggest matches for you:

radius-search-google-maps-joomla-01

And when you press the search button, the map page will be loaded with the resulting markers:

radius-search-google-maps-joomla-02

 

You can see a working sample of this module in the demo section > sites using Geocode Factory.

 


Plugins configuration

In this section we want to speak about the 'basic' plugins, that are included in the Geocode Factory package :

  • Geocode Factory Article
  • Community Builder profile
  • Jomsocial profile

There is also others plugin that are more specifics, and not included in this package. Please refer you to their related detailled documentation chapters bellow :

  • Sobipro Map Search
  • Community Builder Map search

Introduction to plugins

For the most part, Geocode Factory doesn't store any data itself and requires third party components to create it. Geocode factory is a mapping extension that gives you a new way to display data....it doesn't create data itself. Sometimes these third party components do not have internal Geo-coordinates, or don't allow the extension to geocode data on it's own. This is the reason we provide some specific plugins. Depending your environment and your goal, you may or may not need to install additional plugins.

All plugins are installed at once with the Geocode Factory package.

plugin-comp-explanation

Directory components

If you are using one or more of the following components to manage entries, ads, events, on your site.

Sobi2

There is nothing to install. Since Sobi2 2.9.0 the coordinates fields are installed by default within Sobi2. If you have deleted the fields, you need to create 2 custom fields named field_latitude and field_longitude (custom names are supported). To Geocode the entries, you have 2 choices :

  • create your own geocode script (see here)
  • use the Geolocalise plugin for Sobi2 (Sobi2 plugin), that offers many features like auto-geocode during Sobi2 entry creation, picking a point on a map, geocoding from gallery image, batch geocode...

Sobipro

Field plugin

There is nothing to install as the component has internal coordinates fields. To geocode the entries, you can use the Geocode Factory batch geocode function. You can already buy the SP-Geomap field (club members only). Geocode Factory is 100% compatible with this application, and if SP-Geo Field is not installed, we create these fields. See here how Geocode Factory works with Sobipro for more details.

Search plugin

We also have a search plugin that can filter the internal search function of Sobipro results that will allow you to display those results on a map! Of course the plugin is also compatible with our Sobipro Radius Search Application. This is a commercial plugin and information can be found in the Sobipro map Search chapter. Use the Joomla! installer to install this plugin.

Mosets Tree

There is nothing to install, the component has internal coordinates fields. The events, are geocoded automatically during the creation. You can also use the Geocode Factory batch geocode function.

Adsmanager

There is nothing to install, the component has internal coordinates fields. To geocode the ads, you can use the Geocode Factory batch geocode function or install the Adsmanager’s Geomap plugin provided by Joomprod. It allows to geocode the ads during the creation process. This plugin is 100% compatible but not required.

Profile components

If you are using one of the following components to manage your users profiles, Geocode Factory will allow you to display users on a map.

Community Builder

Profile plugin

Community Builder doesn't have any coordinates field, and doesn't support geo-locating of members. To resolve this situation, we have created a plugin to display a map on the user’s profile, and geocode the user’s position. To get the user's coordinates, multiples methods are available :

  • geocode before or after profile creation
  • pick a point
  • browser’s position

It uses the Google maps v3 API, and shows Geocode Factory maps or Static image maps to display the user’s position and supports up to 3 addresses per user. The plugins will install the 2 fields for latitude and longitude, but the usage of custom fields for latitude and longitude is supported too.

This plugin is included into the Geocode Factory package file and is installed automaticaly at same time as component.

Search plugin

We also provide a search plugin that can filter the internal search function of Community Builder results. This is a commercial plugin and can be found here 'CB Map Search'. Install it through the Community Builder plugin interface.

Jomsocial

Jomsocial use internal latitude and longitude fields to store the user’s position. Since Jomsocial 2.0, the user’s position is geocoded by Jomsocial itself. We have create a plugin to display a map on the user’s profile, and (useful for Jomsocial before 2.0) geocode user’s position.

This plugin is included into the Geocode Factory package and is installed automaticaly.

Calendar component

Jomsocial Events

There is nothing to install, the component have internal coordinates fields. The events, are geocoded automatically during the creation process.

Jevents

There is nothing to install, the component have internal coordinates fields. To geocode the events, you can use the Geocode Factory batch geocode function or install the Geolocation component provided by the Jevents editor.

Content component

Joomla articles

Geocode Factory allows you to place a map in Joomla content articles. The data is saved into a separate table and are Geocoded by our plugin. Please see article describing this implementation process in the documentation. This plugin is located into the Geocode Factory package and is installed at same time like as component.


Plugin : Joomla content

Introduction

This plugin allows you to geocode any Joomla! article, without adding any other fields or any core files modifications. The geocoding process takes place during the article "save" process, based on an address written into the article.

Configration

Since we already have the plugin installed, let’s see how to configure it :

In the Joomla! back-end, navigate to the Plugin Manager and select the Geocode Factory Articles Plugin. You should be able to see the plugin successfully installed, like the following screenshot.

Geocode-Factory-articles-how-to-configure1

The next step is to select the plugin and enable it by clicking on the “Enable” icon. The plugin is now enabled and you can start its configuration and settings. The following parameters are the ones that you will need to set up from the Plugin interface:

Geocode-Factory-articles-how-to-configure2

 

  • Id of the used map : This is mandatory. Since Joomla 1.6, you can select the map from a dropdown list. Before this, you need to specify the ID of the Geocode Factory map to display on the Joomla! article. You can find the map id in the Geocode Factory component, map manager. All settings for the maps (map type, size, template, ...) are inherited from this chosen map. IMPORTANT: If the ID of the Geocode Factory is not specified, in your frontend Joomla! article you will see the following error message: 'There is no published map or bad map id.'
  • Show map : By selecting 'yes' the map will be shown in the Joomla article. This is useful if you want to display a map at the plugin code location within the article. If you select 'no', the plugin code will be simply removed. In both cases, the article can be shown as a marker on global Geocode Factory maps.
  • Map type :Set the type of the map (Geocode Factory map or static map) that you need to use in the Joomla article. 
    • Geocode Factory map, set it up on Geocode Factory component before use it in article. IMPORTANT : if you seen in Joomla article the following error message : "The map placeholder [map] is required, and not found in your map template..." then please be sure you have set a map template in the map manager.
    • Static map, will show an generated image for your Google map into the Joomla article. This can be very useful for loading performance, if you just need a map to illustrate the article.
  • Google server : you should use the Google server from your country. For examples google.it or google.co.uk. This can be useful for Geocoding in cases where the same address exists in multiples countries.
  • Map zoom : define the zoom level of the map as an integer value. A value between 12 and 15 will be just fine. You can already leave this blank or 0, and the default viewport will be calculated based on the Geocode Factory map ID.

After all parameters are set, please save it.

Plugin usage

After successfully finishing the article plugin configuration, from the Joomla! back-end article manager select the article (s) where you need that Geocode Factory Map to be shown and/or articles that need to be visible on the map and enter the following plugin code syntax into the text :

  • Code : {myjoom_gf xxx} code, where xxx is the address.
  • Sample: {myjoom_gf Houston, Texas, USA}

The position where this plugin placeholder is written is important, it will be replaced by the map if you selected the display map option. You can embed the code into an article {myjoom_gf ...}, and the map will follow the styles.

 

geocode-plugin-code-article-edition

At the moment the article is saved (or applied), the entered address is geocoded by the plugin, without any other intervention. Repeat this operation in each article in which you need a map. In each of them, only a single map will appear where {myjoom_gf xxx} is located in text of page. The map will show the positions according with each address, introduced separately in Joomla articles. Note : This can be done by editing article from back-end or front-end.

Now, you can create a markerset based on Joomla! articles and you will see any geocoded article on your map, at the right position.

Geocode-Factory-articles-how-to-configure3

Case study

Imagine a Joomla! site that displays tourist spots in a country. There will be a section named Spots, and 3 categories named : Zoos, Monuments and Sports. In each category you have several articles for each park. That will give you :

  • Spots / Zoos / Zoo 1
  • Spots / Zoos / Zoo 2
  • Spots / Zoos / Zoo n ...
  • Spots / Monuments / Monuments 1
  • Spots / Monuments / Monuments 2
  • Spots / Monuments / Monument n ...
  • Spots / Sports / Stadium 1
  • Spots / Sports / Stadium 2
  • Spots / Sports / Stadium n ...

Now, each article describe the place with several text, images and the famous {myjoom_gf xxx} where the xxx is replaced by the address of each park.

google-maps-in-joomla-article-geocode-01

When you save the article, the address is automaticaly Geocoded. The frontend result is :

google-maps-in-joomla-article-geocode-02

 

In Geocode Factory there are 2 maps :

  • Article map : basic map, without controls, map 200x200px
  • General map : main map, with several controls, like radius search, route planner, side list, 100% width ...

And 4 markersets :

  • General markerset : linked to "article map", with a basic icon, simple info bubble
  • Zoos, Monuments and Sports markersets  : 3 markersets linked with "main map", each markerset has its own icon (zoo, monument, sport), and detailled bubble, each is based on hes category.

On main page of site, there is the big general map, that contains all markers on the same map (zoos, ...), and a selector for each type, and when user go on different articles, he see the current map.

google-maps-in-joomla-article-geocode-03

This plugin allows you to geocode any joomla article during the saving process, based on a address writed into the article. Since we already have the plugin installed, let’s see how to configure:

1) Through the Joomla Administration Panel navigate to the Extensions/Plugin Manager and select the Geocode Factory Articles Plugin. You should be able to see the plugin successfully installed, like the following screenshot

Plugin : profiles components

Introduction

This plugin allows you to add a map into the user profile, and to geocode based on the profile address. There are 2 versions of this plugin depending on the profile manager you use:

  • Community Builder
  • JomSocial

In addition to using a Geocode Factory map, this plugin also offers an option to use a static map (image map), which can potentially be an advantage in a page's loading performance.

This tutorial is both for Community Builder and Jomsocial, the plugins have similar features and configurations, and where there is a difference we will indicate it with a "CB" or a "JS".

Installation

The plugins are installed with the Geocode Factory package. Including the CB plugin. You have nothing to do.

Configuration

Once the installation is done, you will need to publish the plugin just like any Joomla! plugin. You can open the plugin configuration and edit the settings. You will find more info about publishing the plugin in the CB or JS documentation.

Requirements

Geocode Factory map

To use the profiles plugins, you need always one Geocode Factory map even if you select the static map. This is because it uses primary settings from a custom map regarding size etc. The static map creation happens on rendering which is where the speed advantage comes in to play. Our advice here is to create a very simple map, don't use side controls, just the [map] placeholder in the map manager, to prevent user confusion.

Geocode Factory Markerset

If you use the dynamic map option, you need to have/create a markerset that include all users. Then, the map will always be centered on the current user.

Field assignments

First we need to map the fields to link the profile location fields with the plugin. For example, if we have a field named 'country' in the CB/JS component that will content the user's country, we need to write in the name of this field in the plugin's field assignation. In our example : 'field_country', or 'cb_country' (the name of the field).

Because the plugin supports 3 addresses per profile (like home/work/vacancy) there are 3 field assignment areas. In the following example we use 2 addresses, primary and secondary. For both we have used the same country field, and different cities field.

profile_plugin_001

CB : Custom CB fields usually start with cb_ ... as cb_office_zipcode

JS : Custom Jomsocial fields usually start with FIELD_ ... as FIELD_OFFICE_ZIPCODE

Coordinates fields

CB : the coordinates fields are always created by the plugin, and are named 'cb_plug_lat', 'cb_plug_lng', 'cb_plug_lat2', ... and all field are created even you use only one address per profile.

JS : since version 2.0, Jomsocial utilizes internal coordinates fields. You can use them by selecting the 'Use Jomsocial internal fields'. This is used for the primary address only! If you use a second or third address per profile, you need to create the corresponding custom fields in JS (FIELD_LATITUDE_2, ...) and enter the field names appropriately. Here is an example :

profile_plugin_002

Interface options

profile_plugin_003

  • Number of addresses : Define here how many addresses the plugin will use and geocode for this application.
  • ID of the Geocode Factory map to use : Here you need to set the ID of the Geocode Factory map to use. First, create a simple map in the component (don't use clustering, center on browser or other advanced features like radius, ...). Second, create a markerset that include the whole community with no filters. This is very important to be sure that at least the current profile owner is visible. See these articles if you need to learn how to create Geocode Factory maps and markersets.
  • Static map (profile view) : This can be used to draw a static, image-based map instead the regular Geocode factory map. This will increase the loading performances as there is no javascript, only an image.
  • Zoom for static map : for the Geocode Factory's map, the zoom is calculated automatically to be centered on the current profile marker. If you are using multiple addresses, the zoom is calculated to see each profile's marker. For the static map, we cannot calculate the zoom factor to include the 3 markers. So you will need to enter the zoom factor manually.
  • Show the icons above map : Draw the icons of the user below the map, and it allow to show or not this information.
  • Labels : it's the text near the icons below the map "Primary address"...

Note : As stated earlier, the plugin must get its static map configuration information (map type, map size, ...) from a Geocode Factory map so for either a dynamic or static map, you must still specify a Geocode Factory map ID.

Community builder settings

If you are using a tabbed view for your profiles, you need to give the tabs container DIV's id to the plugin. The plugin includes the defaults styles (cb_tabmain), but you can have other ones, and is some cases you need to include the parent DIV style too. This is depending the templates.

Geocode options

The geocoding feature gets the profile coordinates based on the field assignment.

Settings options are :

  • Auto geocode during registration : Geocode when user creates the profile.
  • Auto geocode during edit : Run the geocode when user edits and saves an existing profile.

Note : Jomsocial does this automatically (see JS component settings) since version 2, but can be useful if you use custom coordinate fields.

Community Builder only features

  • Show map tab during registration : Allow user to pick a point on a map during the registration. You need to publish the corresponding (primary, secondary, ...) coordinates fields in registration form (see CB custom fields manager).
  • Auto geocode before profile edit : Run the geocode before user edits an existing profile.
  • Add geocode button : add a geocode button that will place the marker on the map dynamically based on the entered address. The user can then drag the marker to get a more precise location.

profile_plugin_005

  • Text for the no fetch checkbox : Text displayed in the 'No fetch checkbox'. This option is important if the user takes more than 1 hour to place the marker in a custom position and you have set the 'geocode at edit' option to yes. If this option is not set under those conditions than the custom position will be overwritten by the automatically geocoded position. If the user checks this box, the auto-geocode function is not executed.
  • Checked by default : define the default state, or hide this option.

Example of results

These are some examples of the plugin with detailed explanations.

This view shows the current user's CB profile. This user has 2 addresses. The zoom and centering is set to center the map over both markers :

profile_plugin_004

 

You can also place the map in a non tab position like in MyJoom CB profiles page :

profile_plugin_006

 

You must do the same thing in Jomsocial with connections lines (because on this map we have not only the profiles markerset ...) :

profile_plugin_007

 

This last screenshot, shows the markers linked by a line (markerset option), feature from the markerset :

profile_plugin_008

 

Static map in users profile :

profile_plugin_009


Plugin : Community Builder map search

Introduction

tuto_illu

This plugin is an optional commercial add-on for the Geocode Factory suite and is designed to display the Community Builder (CB) search results on a Gecode Factory map.

To display maps from Geocode Factory on Community Builder pages, you need to have the Geocode Factory’s module installed and published on the Community Builder search pages where you want the map to display.

Find the Geocode Factory's Community Builder map search plugin here.

Follow this guide to install and configure your Community Builder Search result map.

Installation

You need to install the free Geocode Factory module which is included an installed with Geocode Factory component. This is what displays the Geocode Factory map in a module position. If you do not already have it installed you can install it in the same way as any other Joomla! module and it can be installed over the old version.

Now it’s time to install your new plugin. This plugin is a Community Builder plugin. So use the Community Builder plugin manager to install it. Ensure it is enabled in the CB Plugin Manager. There are no parameters to set as, all setting are in Geocode Factory component. You need just to publish the plugin.

Configuration

To use this plugin to generate a map displaying Community Builder search results you need two things:

  • Map defined for this purpose
  • A marker set in Geocode Factory that is set up for Community Builder

It is configured in the map and marker set. To do this open the Geocode Factory component. Create a map with at least [map] defined to the template.

Make sure that the cache option is set to “no cache” on the “Display Options” tab of the map settings.

tuto_cache-settings

In Geocode Factory, create a Community Builder markerset that shows all Community Builder entries and assign the markerset to the specified map.

Notes :

  • Instead creating new maps and markersets, you can use an existing map and CB's markerset.
  • You will find how to create a map and marker sets in our documentation.
  • You can add more than one markerset (like user’s profiles markers) to the map and only the Community Builder data  (markers) will be filtered in the search results due to this CB search plugin.
  • You can also configure additional filters in the markerset settings if desired.

Now you can display the map. Go to the module configuration for the Geocode Factory module. Edit the module and publish it in the desired module position on at least on the CB search page. Make sure to select the map you configured for this purpose.

tuto_map_selectcb

We can select the Community Builder functions that you do not want applied to this module. For the purpose of mapping CB search results, we want to exclude the profile view by setting the 'Tasks To Hide' settings' to : task=userProfile. This is set by default so you should not have to change this (learn more about the Geocode Factory module).

Known issues

The plugin does not work with the Geocode Factory Component cache enabled. Use the No cache option in the map manager as described in the configuration above.

In summary

In order to configure the CB map search, you need:

  • A CB list, to generate the CB search page
  • A Geocode Factory map
  • A Geocode Factory markerset with, at least, all markers that can appear into the CB search page (CB list)
  • This markerset published on the Geocode Factory map.
  • At this step, if you create a menu link type "Geocode Factory" in Joomla, you can show a map with all your community members markers
  • Now publish the (free) Geocode Factory module on the CB list (search) page (you can also publish it on other pages).
  • Enable the CB map search plugin
  • Now when you do a search on CB, the result are filtered on the map

Needed products :

  • Geocode Factory component
  • CB map search
  • Geocode Factory module (free)

Plugin : Sobipro search

Introduction

tuto_illustr_searchplugin004

This plugin is an optional commercial add-on for Geocode Factory and is designed to display the Sobipro search results on a Geocode Factory map.

To display maps from Geocode Factory on Sobipro pages, you need to have the Geocode Factory’s module installed and published on the Sobipro directory pages where you want the map to display. It MUST, however, be published on the search page to show the search results..

Find the Geocode Factory's Sobipro search results plugin here.

Follow this guide to install and configure your Sobipro Search result map.

Installation

You also need to install the free Geocode Factory module which is included and installed with Geocode Factory component. This is what displays the Geocode Factory map in a module position. If you do not already have it installed you can install it in the same way as any other Joomla! module and it can be installed over the old version.

Now it’s time to install your new plugin. This plugin integrates with with SobiPro, but is a Joomla! plugin. So use the Joomla! installer to install it. Ensure it is enabled in the Joomla! Plugin Manager. There are no parameters to set as, all settings are in Geocode Factory component. You need just to publish the plugin.

Configuration

To use this plugin to generate a map displaying Sobipro search results you need two things:

  • Geocoded Sobipro entries
  • Map defined for this purpose
  • A marker set in Geocode Factory that is set up for Sobipro

It is configured in the map and marker set. To do this open the Geocode Factory component. Create a map with at least [map] defined with the template tuto_map_settings

Make sure that the cache option is set to “no cache” on the “Display Options” tab of the map settings.

tuto_cache-settings

In Geocode Factory, create a Sobipro markerset that shows all Sobipro entries and assign the markerset to the specified map.

tuto_markerset

Notes :

  • Instead creating new maps and markersets, you can use an existing map and Sobipro's markerset.
  • You will find how to create a map and marker sets in our documentation.
  • You can add more than one markerset (like user’s profiles markers) to the map and only the Sobipro data (markerset) will be filtered in the search results due to this Sobipro search plugin.
  • You can also configure additional filters in the markerset settings if desired.

Now you can display the map. Go to the module configuration for the Geocode Factory module. Edit the module and publish it in the desired module position on at least on the Sobipro search page. Make sure to select the map you configured for this purpose.

tuto_map_select

We can select the Sobipro functions that you do not want applied to this module. For the purpose of mapping Sobipro search results, we want to exclude the detailed Sobipro view by setting the 'Tasks To Hide' settings' to : pid=?. This is set by default so you should not have to change this.

Note : Another cool feature is that the module can already filter the Sobipro entries depending on the current Sobipro displayed category. For this edit the markerset that show the Sobipro entries, and set the ‘Auto-categories’ option to Yes.

FAQ

Do I need to create a dedicated link for the Sobipro search results?
No, the module just needs to be visible on the desired position. Of course you can publish it to a dedicated Sobipro Search menu link if desired, but it is not necessary you can use the built in Sobipro links.

Known issues

The plugin does not work with the Geocode Factory Component cache enabled. Use the No cache option in the map manager as described in the configuration above.

As Sobipro, the support of cookies is mandatory.

 

Applies To

Geocode Factory 3