Knowledge Base - Tutorial : Radius Search Application

Introduction

The Sobipro Radius Search application is a native SobiPro Application (plugin) and fully integrated with and installed within SobiPro.

The Radius Search allows you to add a field into the native SobiPro search form to be able to add both centerpoint and radius distance criteria to the SobiPro search function. It works in conjunction with and is entirely integrated with that form. You can search just by radius distance or with any combination of native SobiPro search criteria.

The main features are :

  • Select any address arrount the world as center point (no additionnal database installation)
  • Locate me function as center point
  • Customisable radius values and unit (Kilometers, Miles, Nautical miles)
  • Customisable search field label
  • Show distance from center on Sobipro vCard's 
  • Full customisable distance display on vCars (1025.587 km, 1'025,6 km, 1.026km, ...)
  • Priority area for selecting center point (if the area is Texas USA, then typing Paris, return Paris, TX, and not Paris, France) 

Installation

Required

To use the Radius search application (plugin) you need :

  • Sobipro installed (at least version 1.05)
  • SP-Geo field plugin installed or Geocode Factory**
  • Geocoded Sobipro entries (the entries must have latitude and longitude)

Note : the plugin is compatible with the Geocode Factory module and Geocode Factory search plugin.

      ** Geocode Factory installs the SP-Geo fields database table if the SP native field does not exist.

Download

In your subscription you can find 3 files : 

  • mjradius.zip : the Sobipro app
  • sprs_search_result.zip : the optional joomla plugin
  • mod_sobiproRadiusSearch.zip : the optional joomla module

Installation

The Radius Search Application is a native Sobipro application. You need to install it through the Sobipro application manager. Follow this procedure :

  • Go to your Sobipro backend
  • Open the Application manager
  • Install the Radius Search Application (confirm installation)
  • Browse to the applicable Sobipro Section
  • Under the applicable ‘Section Applications’ click on Radius Search to open the application’s control panel:
  • Configure the Radius Search plugin as per specific needs.
  • Follow the bellow instructions to integrate the application output into the search form and the vCards templates.

NOTE : this application need no other complex geo database to be install (as on Sobi2...)

Dont forget to enable the application under the appilcation list of Sobipro, and for each section where you need to use it. See bellow captures :

sobipro_radius_search_011

sobipro_radius_search_012

Update

There is (at this time) no repository for this application. To update, please follow this procedure :

  • Download the last version (under your profile page on myjoom.com)
  • Go to your Sobipro backend
  • Open the Application manager
  • Install the new release over the currently installed version
  • The Application is updated

Configuration

There is some options you need to configure :

sobipro_radius_search_008

  • Order ID: please enter here your order number, this will register the plugin. Plugin will not function without this.
  • Enable: this option will enable or disable the plugin in the search form.
  • Radius field label: Allows admin to enter custom label for field
  • Unit to use: Defines the unit to be used for the radius calculation. You can use kilometers (km), miles (mi) or nautical miles (nm).
  • List of distances: Enter the list of distances you want to appear in the front-end search form in the drop-down box, separated by commas. Example : “10,20,50,100” (without the quotes) will display in the front-end a list of these 4 distances. If no valid entry is provided by the user in the search form, a default value is used witch corresponds to the first number in this list.
  • Calculate Distance For VCards: enables the background calculation for determining distance from start point of search. Only needed if you display distance on vcards so it can be disabled to save resources if not needed.
  • Order Results By Distance: Option to sort vcards by increasing distance when doing a search.
  • Google Logo: options for displaying Google logo on search form. It is required by the Google terms of use so use at your own risk. Note since last google API the logo come automatically in the list (*see note 2).
  • Input Width (optional): This is an optional parameter that allows the user to specify the width of the starting point input box. it also controls the width of the dropdown box that opens for the autosuggestions.
  • Use “Locate Me” Button: enables the option on the search form to locate users based on their browser location. It can be off, text or an icon. Works with mobile devices as well. *see note 1.
  • Number style in vCard: Here you can define how to display distances in vCards and lists, for example : 1000,00 or 1,000.00 or 1 000.0 or 1'000 or ...
  • Locate me on page load: Populate the center point with the current user's (browser) position on page load or leave empty (*see note 1).
  • Geocode mode: There 2 main methods of geocoding the center point of the search radius: 
    • The Autocomplete (preferred) consists of a list of predictions that populate below the search box as you type. If you type "Par" the predictions are Paris, France, ... The preferred choice can be made using the mouse or by using the arrows to select the desired option. With this method you have many settings in the next section of the admin page and are described here:
      • Limit search by area : This option allows the user to limit the search in a certain geographical area. This area is defined with 2 points. See this article.
      • Inputbox text : By default the input box contains a light text "Enter a location...". This text is localised (translated) based on the user's browser. You can customize it by entering what you want, enter a space to have no text, or leave empty for default text.
      • Country : You can enter a ISO 3166-1 Alpha-2 country code. Like fr for france, it for italy, de for germany. This will limit the autocomplete suggestions to locations ONLY within the specified country. (currently only one country code is allowed at a time)
      • Google Map variable : This optional setting allow you to link a google map with the current center point geocode. Then the location they are visible on the map will be predicated in priority. You can use any google map or use the Geocode Factory Sobi2 search map. Here you need to display the search page HTML code in your browser and locate the variable name used to define the map (usualy is map). In Geocode Factory, simply activate the debug mode to see the map name!
    • During input method is "on the fly" (durring input), and geocoding the user entry when the focus quit the input box. It can take several seconds (from 0.01 to 2 secs ... during this time the search button is hide), but the user can enter what he want. When the user clicks the Sobipro search button the search will return entries in the defined radius.
    • Hybrid method is the mix of the 2 previous methods. If the user type 3 letters of New York, and select the New York, NY item of the list, this value is used. Otherwise, if the user the user dont select one proposed value of the list, then the addresse is geocoded from the input.
  • Default Center: this is an optional setting that will override the Geocode Factory map settings on the search page and allow you to specify a default starting point for the search input field centerpoint on page load. You can of course manually enter any point you want after that to run a different search as well. This setting will ALSO center the displayed map on that entered, default location. this of course will also change if you alter the search parameters.
  • Sales area field: define the Sobipro custom field you want to use for the entry radius. See bellow to understand of the sales area concept work. 

    Sales area display mode : define the format to display the distance on the vCards for the search result list. If the distance from center is in the radius, then the distance is displayed (depending the formatting settings) like 8,5km. But if the entry is in results because the sales area radius is intersecting the radius search, you can select if you want to display the real distance (can be higher regarding the radius search), the radius distance (maximum value) like 5km, even if entry is at 8,5, or the maximum and the difference : 5km + 3,5km.

  • Exclusion field and filter:To select a range of records that will appear even if they are not within the searched radius, select a field to test, and parameters to test it with. Please note that this field must be set up already, and it can be a single input box, a select box or even a multi-select box or checkbox group. There are a number of conditions that you can test for:
    • A set value – to do so, enter an equals sign, followed by the value in single quotes (eg: =’featured’)
    • Greater than or less than a given value – to do so, enter a greater than or less than sign, followed by a number, without quotes (eg: >400)
    Note for the Geocode Factory users only - entries selected by the exclusion field cannot be displayed on the map if they are not also within the radius. This is a limitation of Geocode Factory. To display them, you need to create a separate markerset in Geocode Factory.
  • Geo-Exclusion field and value:To select a range of “nearby results” - which are within the same area (country, state, locality, etc.) as a radius search, without actually being within the bounds of the search - select a field to test, and a Google geocode value to match it with. There are a number of different fields that Google produces:
    • “Locality – Long” and “Locality – Short” (eg: “Miami”)
    • “Administrative Level 1 – Long” (eg: “Florida”)
    • “Administrative Level 1 – Short” (eg: “FL”)
    • “Administrative Level 2 – Long” (eg: “Miami-Dade”)
    • “Administrative Level 2 – Short” (eg: “Miami-Dade”)
    • “Country – Long” (eg: “US”)
    • “Country – Short” (eg: “United States”)

Template 

Insert application code in vCard template and search form ?

In order to turn on the Radius Search Application you need to insert some lines of code into the search template (mandatory) and the vCard templates (optional) as follows :

  • Browse to the SobiPro administrator section where the application is published
  • Browse the Section template manager and open the "search" folder under "Section Templates"
  • Click on the "view.xsl" file and add the appropriate code as described below
  • If you want to display the distance from center, you need to edit the vCard template as well as described

RadiusSearchTempl001

Note : see the Sobipro editor's site (Sigsiu.net) to learn more how to edit templates.

The following captures of the code locations are samples. You can move the code where you want and experiment with different locations, but the included examples fit the 3 most common search form scenarios. Only one of them is required.

To display the search fields into the search form, add following code into your search form view template:

  • <xsl:value-of select="mjradius" disable-output-escaping="yes" />

To show the distances into the search results vCards, add this code into your V-Card template:

  • <xsl:value-of select="mjradius" disable-output-escaping="yes" /> (if you use html text in language file - default)
  • or
  • <xsl:value-of select="mjradius" /> (use is you have simple text) 

Note : the Radius Search Application isn't a custom field like some other Sobipro fields (it save nothing in entries), but is an application. This is the reason why you cannot select the position through the custom fields.

Note : the radius search field can be in the extended search part of the search form. In this case the radius search field is not visible at form loading, and you need to click the 'Extended Search' button.

Search form template

RadiusSearchTempl002

vCard template

RadiusSearchTempl003


Usage

Once the Radius Search Application is installed and configured, and the SOBI Pro templates modified, you can start your first search query based on the radius. For the following example we assume you have activated all options.

Step 1 - selecting the radius center

Go into your search form and you will see a new search field labeled what you named it in the configuration (or the default value). In the below sample it is 'Start Point' :

sobipro_radius_search_007

You can type any part an address into this field, and the plugin will try to find the address for you.

sobipro_radius_search_001

When you have entered enough of the address for Google to recognize your entry, you will see the correct suggestion in the list. Select it by clicking in the suggestion list. The coordinates of this location will be used as radius center.

If you want to use your current position, simply click the ‘Locate me’ button, and the plugin will geocode your browser location and write it into the input box. Now that we have a center point, we can go to step 2.


Note 1 : To use this feature you must accept the permission dialog in your browser.

Step 2 - selecting the radius

Select a radius distance you want to search within from the drop down box :

sobipro_radius_search_002

These distances come from the back-end parameters you entered above (eg: 10, 20, 50, 100)

Step 3 - selecting other Sobipro filters if desired

If you don’t choose any SOBI Pro filters the search will return ALL entries within that chosen radius.

Step 4 - Click search button!

Search results will reflect the the entries in the selected radius, from given center point that meet any Sobipro search criteria you entered.

Here is a sample search that finds all results within a 50 miles radius of Sun City, AZ.

sobipro_radius_search_004

And here the same search with a custom search on the keyword 'sam':

sobipro_radius_search_005

 

Understand the sales area concept : 

Imagine we have a list of companies that provide service. Each company can have a given geographic area that the company works in. Each company can define the maximum distance (radius) from its office (center point) that it covers. To better understand, we have make a little capture :

sales area

You can see here that each company has a different sized circle, that represents its own coverage area. 

The idea is that when the user does a simple radius search on the map, with a center point, and a distance, any entry whose COVERAGE AREA falls within the search parameters then the entry will also appears in the results. The difference between this and a radius search is that even if the center point of this company is not in the radius search it will still appear. Let’s say you want to find a company that does business within 75 miles of you. If a company is located 100 miles away, using the traditional search they would not appear in your search results. However, if that company’s work area is within 50 miles of its office then it WILL now show up in your search because that company will work within 50 miles of your location, therefore, falling within the desired criteria.


 

1. This option will require accepting the permission prompt in the browser to allow the page to access your location data.

2. Since last version, the google logo appears into the suggestion's list. Then I am not sure is the logo is already needed to be visible in the form. See capture :

sobipro_radius_search_013


Known issues

There are the most common issues, you will find more answers in our FAQ.

1 - Javascipt error in debug console.

"You have included the Google Maps API multiple times on this page. This may cause unexpected errors."

This is due because the google maps api is laoded multiple time by different application, and loaded in different method. There is 2 solutions:

  • edit the application, modifiy the part where the api is loaded to be the same path for each, or
  • install this plugin, and enable it this should fix the issue by changing the loading method "on the fly".

2 - Form not showing in search form until a search is done. 

This is due to a known Sobipro issue. To fix this you need to go on the fields manager, locate and edit the field_geo_map and set it as 'searchable : no'. 

3 - Warning displayed in backend. 

20150321-07 59 42-000124

This warning is due because our application use not at 100% the Sobipro API. This message will not affect the Radius search application. No worries about this.

4 - I don't see the application!

After installing you must first clean both the Sobipro and Joomla caches.

Then if you are using the native Sobipro geomap field make sure it is disabled on the search page. Follow this:

  • Open the sobipro Backend
  • Go to the Section configuration > Fields manager
  • Loacate the 'Geomap' field (s)
  • Edit the field, Search Fields Settings > Searchable > No

 

Applies To

Sobipro Radius Search - Application