You can display links on your Website that link directly to specific searches of your interface. To do this, you can add URL parameters to the page on which the MetaLocator code is hosted. These special URL parameters will be passed into the MetaLocator interface code on that page and interpreted as part of the search.
In this example, an interface is displayed on https://www.yourwebsite.com/locations.html using the provided installation code.
If we want the page behavior to automatically pre-populate the postal code field in the postal code search box, we can add a URL parameter as follows:
https://www.yourwebsite.com/locations.html?ml___postal_code=98421
If we want to pre-populate the search box and perform the search automatically, we must add a radius, and the task parameter as follows:
https://www.yourwebsite.com/locations.html?ml___postal_code=98421&ml___task=search_zip&ml___radius=200
Note that the URL parameter prefix is "ml" followed by 3 underscores. Any form variable can be included this in this manner.
To link directly to the location page with ID number 12:
https://www.yourwebsite.com/locations.html?ml___id=12&ml___view=location
To search for a single location with ID number 12:
https://www.yourwebsite.com/locations.html?ml___task=search_zip&ml___id=12
To automatically select categories, use the following syntax, where 99 and 100 are the ID of the category, as shown in the ID column under Categories in the MetaLocator Control Panel.
https://www.yourwebsite.com/locations.html?ml___tags[]=99&ml___tags[]=100
For subscribers to MetaLocator Teams, the user_group_id can be passed as follows
https://www.yourwebsite.com/locations.html?ml___user_group_id=1
To link directly to a Buy Online tab
https://www.yourwebsite.com/locations.html?ml___ml_trigger_cb_online_template =1
Passing JavaScript Variables
An Interface can also accept parameters via a JavaScript variable declared above the Interface installation code as follows:
<script>
var ml___params = {};
</script>
The ml___params array can contain any URL-parameter option as described above. For example, this declaration would cause the City option to be pre-selected as Milwaukee and the keyword pre-populated to "smith".
var ml___params = {"city":"Milwaukee","keyword":"smith"};
Parameters
Parameters, as written it the URL or in the ml___params array can be any of the following:
lang: The language file to load. E.g.
en-GB (1)type: Filter where records have a certain value of the system
typefield.radius: The search radius. This should be a numeric value, e.g.
50id: The id of a specific location. This will filter results down to a specific location.
view: The view is
directoryby default, but can be overridden aslocationwhen linking to a single specific location.limit: The maximum number of results to return
limitstart: The numeric offset of results. E.g. If 5 is provided for limitstart and 10 is provided for limit, the system will return 10 results starting from the 5th result.
tags: Provided as an array of ID values. The values should correspond to the ID of the category (a.k.a tag) as shown in the back-end under Data > Categories.
keyword: Provided as a string to search all data fields for a given keyword.
user_group_id: The user group ID number
task: If provided with a value of search_zip, this will trigger a search to be performed. E.g.
"task":"search_zip"or in the URL asml___task=search_zipfieldname: Any field name shown under Data > Fields. The fieldname should be the "safe" field name as shown under Field Details > Template Markup, without the curly brackets. So"address":"123 MetaLocator"would filter records to show where the address field equals 123 MetaLocator.
Linking Language Files
If your Website has different pages for different languages (e.g. mysite.ca/fr) you can pass the parameter for the French language file as accordingly.
<script>
var ml___params = {lang:"en-US (1)"};
</script>
User Location
If your Website has already collected the user's location, and you would like to pass that information into MetaLocator, set user_lat and user_lng parameters accordingly.
var ml___params = {"user_lat":37.066889,"user_lng":-90.126482};
Categories
To filter by one or more categories, provide the category IDs as shown below. The values should correspond to the ID of the category as shown in the MetaLocator control panel under Data > Categories.
var ml___params = {"tags":[186,187]};
Substring Field Searches
Keyword searches can search any field in MetaLocator using the keyword parameter as shown below, including substring matches:
var ml___params = {"keyword":'woods'};
However, to search a specific custom field by substring, include the _textfield flag as shown below.
var ml___params = {"favoritecolor":'red','favoritecolor_textfield':1};
Where favoritecolor is the code-safe version of the custom field name (no spaces, symbols or special characters). The above would match favorite colors including:
Red, Red, Really Red, Kindred
To simply filter a custom field by a value, without considering substrings, omit the textfield flag as shown:
var ml___params = {"favoritecolor":'red'};
The above would match only exact matches of favorite colors including:
Red, red, rEd
Overriding Interface Settings
You can also override Interface settings by constructing an ml___options array. The settings provided in this array will be merged with the values of the target interface.
var ml___options = {
"theme_color_primary":"#ff7bff",
"theme_font_size":"2"
};
In the above example, the primary color has been set as well as the font size. To discover the allowable names for these settings, check the tooltip in the setting as shown:
Acceptable values are commonly apparent, however; exporting the interface settings can also assist in providing example values for a given setting.
Linking to specific related products
When creating a deep link to an Interface with relational data, such as in a product finder, the parameter to filter by product should be provided in field[table] format. For example to link to a search by SKU,
https://www.yourwebsite.com/locations.html?ml___sku[products]=TX2341
Where TX2341 is the SKU for the product.
When multiple tables are in use, the syntax is field[table], as in favoritecolor[locations] v.s. favoritecolor[products]. The default table is locations if not specified.
Persisting Parameters
Parameters as described above can be used to control the application's initial state. However, to persist those parameters after a user has performed a search, or submitted a form, the parameters may need to be persisted in a search form variable. For example, when filtering by category, as shown below:
var ml___params = {"tags":[186,187]};
The search form will select the categories as shown.
The drop-down will preserve those selections after a search and no further configuration is required. However, in the case of a data filter, such as favoritecolor = red:
var ml___params = {"favoritecolor":'red'};
To persist that selection after a user has performed a search, the favorite color field must be added to the search form:
This will ensure that the favorite color value is maintained as red after any search was performed. To prevent the user from changing the favorite color value the control should be hidden as shown below:
Creating a Custom Search Form
You can also use this method to create your own search form. For example a search form that lives in your Website header.
A simple HTML example follows, where locator.html is the page on which your MetaLocator interface is installed.
<input id="postal_code" type="text" />
<input type="button" id="btn_submit" onclick="window.location.href='locator.html?ml___task=search_zip&ml___radius=200&ml___postal_code=' + document.getElementById('postal_code').value;" value="Submit" />
Embedding the Lead Form
A MetaLocator interface can be configured to display only a lead form. This is useful for creating standalone Lead Capture forms that are installed on external location pages. The Leads captured are saved in MetaLocator just as any other Lead.
To create an Interface suitable for embed as a stand-alone Lead form, follow these essential steps:
Set "Results > Initial State" to Show None
Remove all elements from the Search Form
Set Layout > Show Map > No
Set Layout > Show List > No
Configure your Lead form as desired
This creates an interface that only displays a lead form. The next step is to install the interface in a way that:
Triggers the form to display on page load
Passes in a location ID or an External Key to identify which location should receive the lead.
To do that, place the following script *above* the standard MetaLocator installation code. However, the value of the "id" should be modified to indicate the target location ID.
<script>
var ml___params = {
'ml_trigger_cb_contact_form_template': 1,
'ml_standalone':1,
'id': '1',
'task':'search_zip'
};
</script>
This code can also use an External Key to identify the target location, for example, if the External Key was "Storenum", and the target location was Storenum = 1234, use the following installation code:
<script>
var ml___params = {
'ml_trigger_cb_contact_form_template': 1,
'ml_standalone':1,
'storenum': '1234',
'task':'search_zip'
};
</script>
ml_standalone:1
This parameter prevents the modal from being closed and also removes the usual modal border. Use this when embedding only the form without a locator behind it.
Privacy Opt-out
You can disable MetaLocator tracking of analytics data by passing _opt_out=1 as a parameter to your Interface. This prevents MetaLocator from tracking analytics data and setting cookies. This is useful for when the user has already opted out of allowing cookies to be set elsewhere on your website, and you would like that existing preference respected within the MetaLocator IFRAME.
This disables the analytics system and would therefore allow the user to browse anonymously. This will artificially deflate page views, hits and other events tracked by our analytics system. Similarly, this may also cause the user to be prompted for their location multiple times, as it can no longer be stored in a cookie.