Knowledge Base - Advanced templating

Introduction

There is several metod to personnalise the map output. You can control the design of the map itself, and all around.

sample map

Here we give you some good practices:

  • each item drawn by the component have it's own id, this is useful for CSS styling
  • there is a lot of settings, including in component configuration
  • before you try to change the component core fields, better to contact us, is better to ask us, maybe your request can be usefull for another... 

In the following chapters you will find the keys to fine tune your maps in each.

 


 

Basic method

With this very easy method the map will de drawn in the most easy way, this will fits for the most common needs. 

In the map manager select in the map settings tab Auto-tempalte > Yes.

auto-template

If you need the radius search control, go to the radius tab and select the Radius method > On map.

radius-on-map

 


 

Responsive maps

Geocode Factory 5 an produce responsive maps. There is not a exact method to do this, because each Joomla! template is different, and have it's own settings. 

To make your map responsive, the most easy is to edit your map, and into the first tab, change the map size method from width to max-width and set the width to 100% (not px!).

responsive-map-size

For the height, this is a little different, and depends your template. You can try multiples configurations of settings.

 


Fullscreen mode

You can enable a full screen mode in Geocode Factory 5, for this you need 3 conditions:

  • New method: In general settings, ensure you have the new method enabled
  • Map center point: Select a fixed center point, not the 'all markers' option
  • Enabling some template keys: See the following sample.

Template


<div style="float:left;width:18%;"  id="gf_sideTemplateCtrl">
 Side bar ...
</div>

<div style="float:right;width:80%;"  id="gf_sideTemplateCont">
 {map}
</div>

Template for the map

Template

Geocode Factory is based on a template and placeholder system. To use it you need to disable the Auto-template option (see above). Each used placeholder will be remplaced by the needed control into the frontend. As example the placeholder {radius_form} will be replaced by the radius form itself. The placeholders are alway between braces { } .

map-template-editor

Near the template text area, you can see a button that give you the list of allowed placeholders.

Main content placeholders

{map}

The main placeholder is for the map itself. In the template textarea, remove all existing text (by default there is a sample template), and simply write {map} or insert it from the wizzard.

{number}

Is replaced by the number of markers displayed on the map. For example: "We have {number} members". will return "We have 564 members".

HTML code

HTML code is allowed, then as you can see the possibilities are infinites! As sample a basic template can be:

There is {number} makers on this map:<br />
{map}

And this will return this result:

gf_23_tuto2_02

Once you understand the basic process, you will be ready to use advanced templating.

Localisation and radius

{locate_me}

Will be replaced by a button. When users click on the button, the map will be centered on the user's position and draw a little "X" on the center. This features requier user's acceptance (regarding privacy), and browser compatibility.

{route}

Will be replaced by a DIV element that will display the directions. It also contains a dropdown where you can select the type of directions you prefer: driving or walking. Please read the article "Geocode Factory 5 advanced features" for more detailled instruction about this feature.

google-map-route-display

{radius_form}

Replaced by a radius form. You can place it where you want around the map. The content of the distance list box is defined in the map editor and the radius form itself can be customised, see above chapter.

google-map-radius-search

{near_me}

Wll be replaced by a button. When users click on the button, it will show the markers near the user's browser position. The radius is the current selected radius in the frontend distance list, or if there is no form, the first distance of the list is used (even if not visible).

Markerset selectors

If you link mutliple markersets to your map, the frontend user can hide/show the markers from each different markerset. For example you can have one markerset that contains the profiles of your user community based on Community Builder, and a lot of markerset based on Sobipro (Hotels, Restaurants, Bars, ...), and the frontend user can select exactely what he want to see (Profiles + bars + hotels, ... or Hotels + bars, ...). There is multiple method to draw theses selectors. Of course you can also do not allow users to select the markersets.

Tip: the _1 {xxx_1} version of the control is the same as the main but it will select and load by default the first markerset only in place of all loaded markersets. This is useful if you have big numbers of markers. you can create a empty markerset (without any marker), and name it '-Select-' or 'choose' and move it at the top of the list of markersets for this map. Then your map will be loaded without any marker once one markerset is selected. This is available for all markerset selector : {selector_1}, {toggle_selector_1}, ...

selector method 1

{selector}

This control draws a dropdown list containing all markersets assigned to the currently loaded map. When users select an item of the list, the corresponding markerset is loaded on the map and additionaly an option named -All- is added in the list that display all markersets at same time.

In this sample we have 2 markersets: Offline members and Online memebers.

gf_23_tuto2_05

{multi_selector}

This control draw a listbox containing all markersets of the loaded map. When users select one or more items of the list, the corresponding markerset is loaded on the map. Additionaly a markerset named -All- is added that displays all markersets at same time.

{toggle_selector}

This control draws a list of checkboxes based on all markersets of the loaded map. When users check one or more checkbox of the list, the corresponding markerset is loaded on the map. Additionaly a markerset named -All- is added that displays all markersets at same time.

{toggle_selector_icon}

Same as before, but add's the markerset image before the text. The image can be controled via CSS.

checkbox selector google map

In the above sample, we have simply set a width for each checkbox and text to have a good alignment, and set the markerset image at a smaller size. The icons are the same as the map. This is the CSS customisation to add to the map manager (see following chapter):

.gf_toggeler_item { width:400px; }
.gf_toggeler_item img { width:16px; }

Marker selector

This kind of controls allows the frontend user to select the map markers by clicking them into a side-list. This list of markers can be write as list. Additionally you can control the sidebar's design (see following chapter). To do this this, go into the markerset editor, and you will see a 'Sidebar template' tab. You can work in here exactly like with the bubble template. The bellow samples, are the same but uses the simple list and the template

google-map-sidebar-simple  google-map-sidebar-template

Of course if you have a big amount of markers this list will be long.

{sidebar}

The side list allows you to display the list of any markers of the map. For each markerset a new list is created, this means that if you have one markerset for user's profiles, and 5 other for different directory categories, you will have 6 lists displayed. By default the list contains the entry name and the distance to center if the radius option was used. The list is sorted by distance if the radius option is used and alphabetically if it is not used.

{sidelists}

It's the same as sidebar, but displayed as dropdown list. Can be useful if you create a store locator for example.

 


 

Template Bubble

Introduction

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

This content is defined and based on a template model and it work like the map template. You can edit this template on the markerset editor page.

The loaded bubble is generated by Google Maps and is a part of the Google API, therefore, the basic size of the bubble is defined by Google. We included a back-end parameter in the markerset editor to set a width.

Template

As well as the map template you can use HTML to define the bubble, and you can use placeholders. There is 2 types of placeholders: common placeholders and component placeholders. Like the map template, you find a wizzard button that shows you the list of available placeholders.

jQuery tabs are supported in bubble as well. This is an advanced feature, and you will find a sample template into the placeholer generator. 

Important: Do not forget to select the markerset type (pattern), and save at least one time the markerset to have the correct list of placeholders.

Multibubble

In several cases markers have exactely the same position, for example doctors that are in a hospital will all have the same street/number, and then the same coordinates, this should result all markers on same place, and only one is clickable.

If you enable the clustering in map setting, and set the map maximum zoom at same value like the clustering maximum zoom, the multibubble is displayed when, at maximum zoom you click a cluster. This feature allows you to have all bubble displayed in one unique bubble. .

multi-bubble

Common placeholders

Placeholder that you will find in each case, for all markerset type, regardless the used Gateway (except the Google place gateway).

{title}

This placeholder will be replaced by the title of the current marker. Is the same text like the marker tooltip. If the source extension of the current marker contains a title (typically for the directories components), this value is used. In other case you can choise what field is used to define the title (typically in profile component where you can select the name, username, or any other field).

{id}

Numeric value thet represent the ID of the entry/event/profile represented by the current marker. This value can be very usefull to create custom urls.

{link}

Replaced by the url pointing on the current entry/profile/event. Important: this placeholder does not generate a link, but only draw the URL itself, you are responsible write the html anchor like <a href="/{link}">{title}</a>

{distance}

Will be replaced by a numeric value that represent the distance to the center point of radius. If there is not radius search performed (or no radius set in backend), then a simple '-' is displayed.

{waysearch}

This placeholder will be replaced by a form, that will invite the user to enter a start point, and it will return the pathway to get to the current marker. As start point, the user is allowed  to enter any address, or click an icon to fetch he's position (this last option need to be enabled in settings). This feature require the map placeholder {route} and to be enabled in map settings (see above).

Componenent placeholders

Here is not possible to detail each placeholder, because they are dependant your configuration. As example if you have a Mosets Tree directory designed for a hotel directory you will have fields related to hotels (field_wifi, field_sea_view, ...) or if you have a Jomsocial community you will have field about profiles (field_age, field_gender, ...). The returned valude depends the value of the entry/profile, and the component store method.

Each supported (by default the basic fields types, you can each type if you enable the 'use all fields' option in configuration) core or custom field can be used as placeholder.  Some samples (you wil not see theses fields, this depend your your installation):

{field_age}

Typical text field type values. If your template contains a code like : 'Age: {field_age} years old', you wil see this result: 'Age: 26 years old'.

{field_wifi}

Typical checkbox field type value. Here the resuling value depends how the extension store the value. It can be yes/no, 0/1, ... Then you have mutiple solutions to display the value:

  • If the returned value Yes/No is applicable for you, then simply use the 'Wifi available: {field_wifi}' syntax, to have this result: 'Wifi available: Yes'.
  • You also can have more advanced soltions: using the resulting value to display an image: 'Wifi available: <img src="/images/tick_{field_wifi}.png">' syntax to have a tick based list of options. Of course you will need to have these images: tick_0.png, tick_1.png or tick_yes.png, ... or your_value.png.
  • Another option is to use the value to generate CSS like: <span class="boolean_{field_wifi}">Wifi available</span>. Then you should have CSS styles ready like .boolean_yes{color:green;dsplay:block;} and .boolean_yes{dsplay:none;}.

Just some example, you are free to use your own method.

{field_choices}

Typicaly a mutiple selector list or multiple checkbox. Here is depend the extension, but usualy the returned value, is a list of each value, separated by comas.

{field_images_idx}

In some component there is more than one images, in this case we provide more placeholders, like {image_idx_1}, {image_idx_2}, {image_idx_n}, or {image_idx_1_BIG}, {image_idx_1_MED}, ... In this case the returned value is the path on the image, you need to place the placeholder in a image tag: <img src="/{image_idx_1}" />.

If you are usgin the {image_idx_4} placeholder, and one entry does not have an image, then the returned value is 'media/com_geofactory/assets/blank.png', this is a 1 pixel white image. You can replaced this pixel by a 'no photo' logo named blank.png.

Content plugins

By default the joomla! content plugins are not parsed in bubble, but you are free to enable them in the component configuration.

 


 

Template Sidelist

This template can be used set style to the {sidelist} items on the map template. By default in the sidelist, Geocode Factory draw a simple text links (with distance if a radius search is done). But if you define a template in the markerset for sidelist (as same way like the bubble template), once the map is full loaded, the sidelist is starting loading the template for each marker, one by one as ajax calls. 

If you have a lot of entries, it should be better to load all templates a once, this setting can be enabled in component settings. 

sidetemplate


Radius form

The radius form can be dispalyed in 3 different methods. You can select them on the map editor on the radius tab.

  • On map: the easyest method, all is automatic, the radius form is inserted on the map top place.
  • Basic form: this will display the predefined form, and will be placed in place of the {radius_form} placeholder.
  • Custom form: use the template for the radius, and, like the basic form, will replace the radius placeholder. See bellow how to configure the template.

Radius template

This template is also based on placeholders, and html code. There is the list of available placeholders:

  • {input}: the inputbox where the user can enter the places (city, zipcodes, ...) that define the radius center
  • {distances}: the select list of available distances. You can define the distance in the radius tab
  • {button}: represents the search button

Geocode-factory-understanding-the-radius1

 


 

CSS design

Each element drawn by Geocode Factory have its own ID (id="element_name"), then you can define CSS styles for each of them and have a hight level of customisation. In Map manager and in Makerset manager, you have both a CSS setting inputbox, where you can add CSS styles:

  • Map manager: the style is loaded each time the map is loaded. You can also place here CSS for markersets
  • Markerset manager: the style is loaded only when the makerset is loaded. Useful if the markerset is loaded on multiple maps.

Note: several items have already inline CSS properties (like 'width:150px;'), you can override them by adding the important flag (like 'width:150px!important;').

 


 

Map types

In Geocode Factory you can use any map type, als custom map types. The engine (controls, markers display method) is always Google Maps, but you can have any kind of map content.

As exemple it's very easy to display any map type based on the openstreetmap project (www.openstreetmap.org). Or you can create your how custom tiles based on a aerial image, or custom drawning. For this you need to create compatible tiles. Any map is composed of a list of tiles, and tiles are based on zoom, see the 3 following images, for 3 different zoom. These tiles are based on a airplane large picture to cover a caraibeen island and below the resulting map :

tile 8941tile35767alt

 

custom google map type based on photo

Working with custom tiles

Learn how to display openstreetmap in Joomla. In addition you can set a custom map type as default at map loading. You can add an unlimited number of differents maps types. Open the map editor, open the "Display options" tab, and locate the "Load different tiles" textbox.

For this you need to enter a parameter line for eache type in Geocode Factory map editor. This parametere line includes all needed information to display the map type, like the tiles size, zoom, etc, and the map type name...

Openstreetmap and other custom tiles

To do this you need to generate a simple phrase that include all parameters of this new tiles source. There is a sample of the phrase :

http://tile.openstreetmap.org/#Z#/#X#/#Y#.png|Mapnik|18|Open Streetmap Mapnik|true|256;

And you can add multiple parameters line for the same map, simply by separathe them with a semicolon ; . Any parameter is separate with a line |. And here the description of each parameter with a openstreetmap sample :

  • http://tile.openstreetmap.org/#Z#/#X#/#Y#.png : the url where are the tiles, the #Z# (zoom), #X# (latitude), #Y# (longitude), will be automatically replaced by the current map position.
  • Mapnik : the text of the map type button
  • 18 : the max zoom allowed for this map
  • Open Streetmap Mapnik : the tool-tip for the map type button
  • true : tiles images are png files
  • 256 : tiles size
  • | : separator for the phrase
  • ; : separator if you use multiple maps.

After you have created your phrase you can copy it into the textarea. You can set multiple phrase, separated by “;”, then you will have multiple map types.

Note 1 : if you dont know the size, or the file format of tiles, you can leave the last item empty. Geocode Factory complete the phrase with default values.

Default map type

In the map manager, under the "Google controls" tab, the Default map type contains all available map types, including the custom map types. Simply select the default type loaded at map opening. Aditionnaly you can select what type of map is loaded with the map. We can imagine that you don't load any google based types, and only the custom ones.

Note : you need to save the current map before the custom map type are in the list.

gf_maptype

Bing tiles

You can also include tiles from the Bing! maps, they are loaded into the google map. You can already switch between theses tiles from Bing and even other Google tiles. We have added the support of Bing map because in some places the imagery or maps render better.

 


 

jQuery Ui

By default the Joomla jquery library is loaded. In component settings, you can select a lot of version, and a lot or loading method, including SVN versions. Also you can choice to load no one, and use another extension (like jQueryeasy plugin) to load your libraries.

About the jQuery UI there is a little different, we only provide 1 style (rearding our component package size!), placed in a folder named 'base'. You are free to download any other style, and simply invert both folder names (if the new style is named iron, then simply rename 'base' in '_base', and 'iron' in 'base').

 


 

Icons 

In the media/com_geofactory/ folder, you will find some icons used in Geoocode Fatory. It's easy to replace these common used icons.

common-icons

Applies To

Geocode Factory 5