Wednesday, 04 January 2012 18:11

Locator User Manual

Installing the Component

Install the com_locator package according to the version of Joomla you are using. The module, mod_locator, is not required, but is helpful when you need to create a small location search form, for example, in the sidebar of your site. Install the component in the usual way, as described here.

Adding Locations

The first step to getting a locator on your Web site is adding locations. You can add locations in two ways, firstly, you can add locations one at a time using the "New" toolbar icon found under "Components->Loctor->Locations". Secondly, you can import a spreadsheet of your locations using the "Import" option under the "Components -> Locator" menu.

Importing Locations in Bulk

To import locations in bulk, you must first prepare a spreadsheet with your locations. To get started, download the spreadsheet template from the import screen found under "Components->Locator", then "Import". The spreadsheet template is dynamically built according to any custom fields you may have created. Do not alter the column names in any way, they are specially arranged and formatted as required.

The fields provided by default are as follows:

Name: (required) The name of the location. This becomes the clickable link and effective "title" of the entry.

Description: The description field can contain any HTML text. This includes a basic narrative description, but also pictures, movies, audio clips or entire Web pages.

Published: Published should contain a 1 or a 0. Only published locations will be visible on your site's locator.

Address: The street address of the location. This is the primary field used by our geocoder to assign latitude and longitude. Ensure it contains correct and properly formatted address data. Reserve descriptive text such as "Business Plaza" or "Suite 300" for Address2

Address2: The second line of the address. This information is not used when geocoding the location.

City: The city, municipality or town of the location.

State: The state, province or territory of the location

PostalCode: The postal code

Phone: The phone number of the location.

Date: A date field for tracking when this location was added

Country: The country this location is in. If you have multiple countries, the entries provided here will be used in creating the optional "Country" drop-down list.

Link: A Web site address or other hyperlink for this location. This will be converted to a clickable link.

Email: The email address for this location. This will be converted into a clickable link

TLD: Top-level domain. This defaults to US. The TLD can be used to bias the geocoder for a specific country. E.g. CA for Canada or UK for United Kingdom. For a complete list, see our FAQ.

meta-description: A textual description included in the meta tags of the location detail page. Provided for search-engine optimization.

meta-keywords: Textual keywords for which this location should be matched. Provided for search-engine optimization.

lat: The Latitude of the location. If not provided, the geocoder will assign a latitude and longitude based on the address information provided.

lng: The Longitude of the location. If not provided, the geocoder will assign a latitude and longitude based on the address information provided. NB: Most US locations have a negative longitude (E.g. -93.29409280).

Saving your spreadsheet

Once your locations are entered into your spreadsheet, save the spreadsheet as a MS-DOS CSV. Mac users should be especially careful to select the MS-DOS CSV option as attempts to import a regular CSV from MS Office for Mac will fail.

Once the spreadsheet is created as a CSV, choose "Import" under "Components -> Locator", click the "Browse" button, select your spreadsheet and choose "Save"

The import screen also provides the option to "Remove all entries before import?". This feature, when checked, will delete all locations in your database before importing. This is useful for importing updates to your data. Note, however, if you did not import with a latitude and longitude, your entries must be geocoded again. This can be time consuming for thousands of locations. To avoid this step, after geocoding, export your list and make updates in that spreadsheet. Exported lists will contain the latitude and longitude provided by our geocoder.

Entering Locations one-by-one or Editing Locations

Adding single locations is as simple as filling out a form. To add a single location, go to "Locations" under "Components->Locator" and click "New"

Alternatively, if you are editing an existing location, simply click it's name under "Locations"

Either of these operations will open the Location Editor. This form allows complete control over the content of your locations. The form contains all standard and custom fields.

The Location Editor also displays the rich text editor for the Description field. This very useful control allows for the addition of images, movies, links and rich, formatted text to the location.

Use the various toolbar icons to add content to your location if desired.

Geocoding Locations

Once your locations are imported, the system must assign a latitude and longitude to the location before it can be included in a Locator. This process is called geocoding. There are three methods to geocode your locations: on-demand geocoding, where you can geocode up to 2500 locations while you wait, single or one-off location geocoding, and the background geocoder, which runs constantly and geocodes locations without requiring any action on your part.

Bulk On-Demand Geocoder

The on-demand geocoder will geocode up to 2500 locations on demand. To access the bulk geocoder, go to "My Locations" under "Components->Locator". Clicking on Geocode with no locations selected will load the screen with all of your locations displayed, ready for geocoding. If you want only selected locations displayed, check the box or boxes next to the locations before clicking the Geocode button. To select an entire page of locations, click the checkbox in the title row to select all locations in the list.

Geocoding a single location

There are two ways to geocode a single location: firstly you can check the "Geocode on Save" checkbox when saving the location.

Alternatively, you can choose the checkbox next to the location, click "Geocode", then geocode that single location via the Bulk Geocoder.

Location Manager

Found under "Components->Locator", "Locations", the Location Manager allows you to manage your entries including delete, search, sort, filter etc.

Searching, sorting and filtering

To find or organize the list of locations, you can use the various drop-down lists at the top of the Location Manager to filter the list. Additionally, you can use the "Keyword" box to include a keyword search. You can combine search options to further refine your search.

Publishing, Unpublishing & Trash

To publish or unpublish locations, click the green checkmark in the "Published" column to toggle the publish state of the location. Unpublished locations will not appear in any public search results. To delete a location, click the checkbox next to the location title, then click the "Trash" icon as shown here:

Tag Manager

Tags are the primary method to segment and categorize the list of locations. One location can have zero or more tags. When you tag your locations, you can then create different locators that reference only certain tags. This allows for multiple directories that may share locations. For example, you can tag certain locations as "Dealers" and other locations as "Manufacturers". This would allow you to create two directories, one for dealers, the other for manufacturers. Alternatively, you can have a single directory with both tags, but each is represented by a different icon.

To view or create tags, click on "Components -> Locator" then "Tag Manager"

To create a tag click on the "New" button in the toolbar. To edit an existing location, click the title of the tag to load the Tag Editor.

When adding tags, the most important items are picking a name and a marker icon. Simply enter the name in the Name field and click a marker icon from the marker gallery on the right.

Other fields are as follows:

Customize Marker: This allows you to enter a full URL to a marker icon. This allows you to specify a custom image not available in our marker gallery. When using the SSL option, ensure this link is to an HTTPS resource.

Customize Marker Shadow: Marker icons can cast a shadow on the map. This field allows you to specify a custom URL to a transparent PNG that represents the marker shadow

Tag Group: If you would like to group tags into collections, you can enter a text label for the group. For example, if your tag groups include Store Types and Product Types, where store types may include "Reseller Locations", "Service Centers" and your "Product Types" group includes "Mobile Units" and "Stationary Units", you can enter "Store Type" in the Tag Group field when adding the "Reseller Locations" tag and the "Service Centers" tag. This will allow the display to the user as follows:

Field Manager

Custom fields are an important part of the locator. The locator comes with a series of "system" fields that are not edittable; however you are able to add as many fields as allowed in your level of subscription.

To manage fields, go to "Components -> Locator", then "Field Manager".

As with all locator screens, to create a new item, click the green "New" button in the toolbar or click the title of the existing field to open the Field Editor.

The field editor allows the following fields:

Name: The name of the field. This could be Hours, or Manager Bio or whatever custom field you want. The template tag is derived from the name by removing the spaces and special characters and adding curly brackets (E.g. {hours} and {managerbio}.

Field Type: This controls how the field is displayed and what control is used during data entry. Text is the most basic field and allows for a basic text entry. Other custom fields types include:

Link: Text in a link field is treated as a URL and wrapped in a proper anchor tag.

Email: Text in this field is treated as an email address

HTML: This field is similar to the system Description field, in that it allows any kind of HTML entry. HTML fields can include a lot of different kinds of data, that is, anything that can be included on a web page.

Visitor Field: This field is for use when providing an optional data entry form for your Web site's visitors when the general public is allowed to add locations. If a field is a Visitor field, the system will include it on the form presented to your Web site users. Set this to "No" for fields that you do not want shown to your visitors.

Locator Menus

Once your locations are imported, and you have your tags created you must create a Joomla Menu Item of type "Locator".

Locator Types

When creating a locator, you can choose from the various types. The most common types are the "Directory" class of locators, those that provide a listing or directory of locations that can be searched by your end user.

  • Combined Google Map & Directory Layout: Our most popular and flexible layout. The combined layout displays a text list of search results alongside an interactive map. For an example of this layout, view a demo of the Combined Google Map and Directory Layout.
  • Google Map Layout. The Google Map layout displays only the interactive map when displaying search results. View a demo of the Google Map Layout.
  • Directory Search Layout. This is a text-only layout, with no map. It includes a single or mulit-column paginated display. View a demo of the Directory Search Layout.

Locator Settings & Options

Each locator type has scores of options that we're always updating, so detailed descriptions of each element is not included in this manual. For a complete description of each setting on the Locator, pause your mouse over the setting name to review additional descriptive text regarding this feature. Locator settings are grouped in the following categories:

Form Settings: This group controls the fields displayed on the form your users see. This includes options related to what search fields are displayed and how they are displayed.
Map Settings: This group focuses on options related to the map displayed on the primary locator page. (Not included in the Directory Search Layout)
Data Settings: This group allows you to choose what data will be displayed on this Locator, including tags, countries and other filters.
Style Settings: Style settings contain "look and feel" related options including the color scheme, font and object size choices.
Field Settings: This group contains primarily the Item Templates, which are used to control the ordering and layout of your location fields.
Location Detail Page Settings: Location detail settings control the options available for the page displayed when a user clicks on and displays a single location.
Advanced: Advanced settings including, most importantly, your cache settings.
Published in Locator