Knowledge Base - Gateway for Community Builder
What is it
Community Builder is a leading Joomla user management component. Using Geocode Factory's Community Builder gateway and profile plugins, you can associate one or more sets of coordinates to each of your Community Builder users. Further, you can then add maps to your Community Builder user profiles (profile plugin), as well as collectively display the locations of your users as markers on another map (gateway plugin).
Note: In order to use Geocode Factory's Community Builder gateway and profile plugins, you need to have Geocode Factory 5 component already installed.
The profile and gateway plugins for Community Builder are not included in your Geocode Factory 5 package by default.
The Community Builder Gateway contains a zip file named xxx.UNZIP_FIRST.zip file. After you unzip this file, you will see 3 files:
- plg_geofactory_profile_cb19.zip: profile plugin for CB 1.x
- plg_geofactory_profile_cb20.zip: profile plugin for CB 2.x
- plg_geofactory_gw_cb.zip: gateway plugin
Access and Download
Please read the Download, install and update manual for more information.
The CB Gateway plugin file "plg_geofactory_gw_cb.zip" is installed using the standard Joomla installer (please see the main GF5 documentation).
The CB profile plugin file "plg_geofactory_profile_cb.zip" however, is installed using the Community Builder plugin manager. Go to your CB menu and select "Plugin Management":
Scrolling to the bottom of the page you will see the "Install New Plugin" options. The standard way is to use the "Upload Package File" method to browse and then install the plugin.
As stated above, this Gateway package, contains 2 different plugin: the gateway itself, and a special profile plugin. The gateway is used to make the link between Community Builder and Geocode Factory, and the profile plugin is used to create a tab (or any CB position) in the profile to allow the user to define he's position using a map.
Community Builder Profile plugin
Once the profile plugin is installed it should be listed in the Community Builder plugin manager. (To locate this more easily, you can use the filter by adding the text “geocode” for example, like in the following image.) There is nothing you need to configure here and this is mentioned only for informational purposes and so you can verify it was installed properly.
The Location tab and the coordinate fields
When the profile plugin is installed it will add a "Location" tab inside your Community Builder user profiles, as well as 6 new fields in your CB field manager. As you can see in the following images, there are 3 sets (pairs) of latitude-longitude fields available for you to use. This means that you can add up to three different addresses/locations to each user profile for whatever purpose (work, home, etc).
The Location tab:
The CB field manager:
Configuring the Location tab:
The Location tab in your Community Builder tab manager has some basic settings similar to other CB tabs that you may want to configure. Please consult your CB documentation for more details on these.
Configuring the coordinate fields
The 6 new fields in your Community Builder field manager have some basic settings similar to other CB fields that you may want to configure. For example, to select whether to make them visible on the profile (and also where if desired). Please consult your CB documentation for more details on these.
Configuring the plugin itself
There is 2 different modes to configure the profile map:
- Simple map: This will display a simple google map, with one centered marker. By default, the map is very basic. But, in addition, if (not mandatory) you select a Geocode Factory map that contains a CB markerset, the map will take the configured zoom, size, map type and bubble. This is a very quick method.
- Geocode Factory map (advanced users): This option will allow you to place a real Geocode Factory map, where you need to configure all settings, is a little complex, but the result can be more powerful, with more features.
To configure the plugin:
- ID map 1: This is the ID of the Geocode Factory map to display on the profile view. You will find the ID on the backend map manager of the Geocode Factory component itself. You need to select a map that has at minimum, all CB user displayed on it to ensure the current profile user will be displayed. You can configure your markerset to load just the markers in a radius near the current profile.
- ID map 2: Same as above, but only if you are using multi addresses.
- ID map 2: Same as above, but only if you are using multi addresses.
- Container front: Here you can enter the tab id of your custom tab manager (if you use the default, leave this blank), then, when this html element is clicked, the map is redrawn.
- Conainer edit: Same as above, but for the addition of profile. Also only for custom tab.
- How many maps: Define the number of maps to display and edit on the profile. Leave 1 if you are using only one address per profile.
- Zoom: You can force the zoom for the designated Community Builder map or leave Auto, to use the Geocode Factory map setting as specifiied in the component itself.
- Register map: If yes, the map is displayed in registry form. In this case you need to publish the lat and long field in registry as well, although you can hide them using CSS.
- Patterns selectors: define what pattern is used for the address fields. To define the patterns you need to go in the pattern manager in Geocode Factory 5. You can use 3 differents pattern if you use the multi-address feature.
- Auto-fill address: If yes, this will display a checkbox (you can select if she's checked or not by default) in the frontend, that will allow the user to automatically fill the CB profile address fields from the map (if the user use the autocomplete box or pick a point on the map). And you also have the choice the write the address like '15, Station road' or 'Station road 15'. See the above special chapter.
- Auto-fill address text: This option allows you the select the frontend text to display near the related checkbox.
- Auto-geocode: If yes, this will display a checkbox (you can select if she's checked or not by default) in the frontend, that will allow the user to automatically geocode its position, based on the entered address. This geocode process is send after the click on the save button.
- Auto-geocode text: This option allows you the select the frontend text to display near the related checkbox.
Note: with regard to the CB plugin structure, is not possible to place a map selector here, only a text input for the map ID.
Community Builder Gateway plugin
Inside the joomla “Plugin Manager” you will find the installed gateway plugin. To locate it more easily, you can use the filter by adding the text “geocode” for example, as in the following image (the 3rd one).
Configuring the CB Gateway plugin you have the following options:
Here you select the colors of the lines drawn between the markers for each purpose. To do so click on the hexadecimal color code and select the color from the palette pop-up. Or alternatively, you can type in the hexadecimal color code of your choice in the field directly.
- Colors of the lines between my addresses: This option will draw lines between the markers belonging to the same user. For these lines to be drawn on your map, you need to enable the “Connect my addresses” option, by setting it to yes, in your map’s settings. This specific option is found in the “Map Settings” tab of the “Map Manager”.
- Line color between friends: This option will draw lines between the user markers of friends, as determined by the CB friends functionality. For these lines to be drawn on your map, you need to enable the “Connect friends a mettre dans plugin CB” option, by setting it to yes, in your map’s settings. This specific option is found in the “Map Settings” tab of the “Map Manager”.
(If you do not use these two features, you do not need to configure anything here)
Pattern manager and Community Builder
When you enter the pattern manager you will see that a default pattern for Community Builder is created automatically when you install the plugin.
As we mentioned before you have three sets of available coordinate fields to use with CB. This means you can create up to 3 different patterns, each one with it's own coordinate set assigned (read the main documentation section "Patterns"). However, there is an unlimited number of custom fields you can make available for determining addresses/locations.
See here how to configure the different fields:
- Latitude: Here you need to select one of the 3 coordinates fields designed for latitude, named cb_plug_lat, cb_plug_lat2 or cb_plug_lat3. Of course for advanced users, you can also use custom created field that contains a latitude.
- Longitude: Here you need to select one of the 3 coordinates fields designed for latitude, named cb_plug_lng, cb_plug_lng2 or cb_plug_lng3. Of course for advanced users, you can also use custom created field that contains a longitude.
- City: Select the field where you are storing the user's city. ususaly is the cb_city field.
- Other address fields: Exactly like the city, select here any field that define the address.
Warning: by default Geocode Factory cannot know what fields you want to use (in CB you can create your own custom fields...), for this reason the latitude and longitude fields contains both the first coordinate-like field. Please check that both are different. If your fields does not appears please apply the second not bellow.
Note: Like described in main documentation, more fields you set for the address, more accurate will be the markers.
Note: If you are using more advanced fields (non-textual), like a country-selector and this field does not appear then you can go in to the Geocode Factory component settings, and set the 'Use all fields' to YES.
The specific settings tab
The options on this tab are generated based on the currently selected pattern. In this tab you can select various different filters for the current markerset allowing you to further customize your data pool. You may also select some other options which are not filter-related.
- Filter Generator: Here you can introduce SQL queries to filter out your results. The Geocode Factory query will be build with your optional filter. For instance, in the example above the condition is that the data in the field "cb_listme" has to be equal to "On". This way, the CB profiles which meet this condition will be used only. The idea here is to have a checkbox field (cb_listme) where your members choose whether they want to have their location displayed on the map "On", or not "Off". Of course this field could be an administrative one instead, it's up to you and what you want to achieve.
Warning: The use of this feature is the most common source of errors that result in no markerset being displayed! 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!
- Select title field: Here you can select the CB field that will be used as the "TITLE" placeholder in the map templates and also when you hover over the markers.
- Select sales area field: Here you can select the CB field that will be used to calculate the "Sales Area". It has to be a numeric value/field. See the Geocode Factory advanced features article to better understand this functionality
- Usergroups to include: Here you can select the Joomla usergroups from which to choose the user markers to display on the map. You can enter multiple joomla usergroups.
- Template for online and offline icon: Here you can enter the HTML template to be used as online and offline icon respectively.
- Draw Lines: Select if you wish to Draw Lines between the markers.
Plugin : Community Builder map search
The Community Builder Gateway plugin allows you to display maps from Geocode Factory on Community Builder search pages. You need to have the Geocode Factory 5 map module (included in base package) installed and published on the Community Builder search pages where you want the map to display.
Please read the Community Builder documentation to learn how to create the search form. In summary, you need to create user lists, based on several filters (you can have multiple lists, with each it's own map). On the list there is a search field, and depending how you have set your custom fields (searchable or not), you can have advanced search options.
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 with a minimum of all searchables users included
Note: You can add more than one markerset. For example you can also display markers from Joomla content articles. They will not be affected by search results. Only the Community Builder profiles (markers) will be filtered in the search results map.
To display the map, go to the map module configuration, select the desired map 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.
Community Builder does not offer any plugin developer interface in its search process to include a real radius search field in the form itself, but... with Geocode Factory and the Community Builder Gateway plugin, you can still offer your users radius search functionality in your community. To do this, simply let the user complete a Community Builder search to generate the markerset data, then perform a radius search on the map itself via the Geocode Factory radius search feature! (It is advisable to place this button near the map for ease of use)
Auto-fill the profile address fields
When a user use your registration form, it's possible to pre-fill the address fields based on the user's position or on a point picked on the map. There is 4 conditions for this:
- Have the used coordinates fields published on the registration form (can be hided by CSS)
- Have a Geocode Factory pattern selected for the address fields 
Now, on the map if you move the marker  (or enter an address, or when page is loaded), the address if fetched.
Geocode Factory 5