Developer Console

From Documentation | Viadat Creations
Jump to: navigation, search

Contents

About

Minimum Requirements

Benefits

The Developer Console is an API inspection and browsing tool for both  Addons Platform Lite and Addons Platform.  It allows one to see most hooks, where they visually occur in Store Locator's interface (both in the admin area and frontend map interface), the addon functions that are currently using each hook, and the visual / HTML output of each addon functions (if there is any)

«Back List of Addons | Purchase Addons Now»

Usage

Addons - Basic Setup

  • All settings are updated under 'Addons' > 'Settings'
  • To create a settings page, create the file: '/addons/{your_addon}/settings-{your_addon}.php'. A simple 'settings.php' file will work too.
  • For additional settings pages, create '/addons/{your_addon}/settings-{settings-page-name-of-your-choice}.php' file
  • Next, create a '/addons/{your_addon}/{your_addon}.php' file -- this is where all code and hooks should be placed, either by including other files or typing directly into the file (e.g. '/addons/db-importer/db-importer.php' is where all your functionality should be included into)

How to Hook Onto the Addons Platform

add_sl_hook($hook_name, $func_name, $priority=10, $args="")

  • hook_name: name of hook established by 'do_sl_hook($hook_name)' (available hooks listed below in 'Hooks (PHP)' & 'Hooks (JS)' sections)
  • func_name: name of function to be added to hook
  • If you would like to use a class function (method), you can simply use the formats "array({classname}, {functioname})" or "{classname}|{functionname}"
  • priority: default - 10; closer to 0 takes higher precedence in order of execution
  • args: arguments to be passed into the function referenced in $func_name as an array


remove_sl_hook($hook_name, $func_name, $priority)

  • hook_name: name of hook established by 'do_sl_hook($hook_name)'
  • func_name: name of function to be removed from hook
  • priority: needs to match the priority of the hook that is being removed (if blank in the original hook, it should be '10' here)


do_sl_hook($hook_name, $hook_type="append")

  • hook_name: any name of your choice to identify a specific hook point that will be used by other functions. Prefixing with '{2 letters}_' is good practice, to prevent colliding with other already established hooks.
  • hook_type: default - 'append'

hook_type options:

'append' or 'append-print' (default)

- prints or executes output at location of hook according to priority

'append-return'

- returns output to a variable at location of hook according to priority

'js{|optional params}'

- prints javascript code into javascript function, which matches the name of the hook. 'script' HTML tags should not be added. Add an optional pipe symbol '|', then a list of params separated by commas after the pipe in order to add parameters to the function (same for 'js-return' hook type)

'js-return{|optional params}'

- returns javascript code output into a variable. 'script' HTML tags should not be added.

'select-{orientation}'

- creates dropdown list to show only 1 hooked function at a time

{orientation} options

- 'left' (default), 'right', 'top'. Refers to the position of the dropdown selector in relation to the function's output.


Hooks (PHP)

sl_addon_head_scripts (Type: Append)

  • Adds additional dynamic Javascript (JS), before 'store-locator.js', where the global javascript variables are created (more information under "Global Variables (Javascript)" section).
  • Example Usage: Good for creating global JS variables to be used in 'store-locator.js'.


sl_addon_head_styles (Type: Append)

  • Adds additional styles/stylesheets
  • Example Usage: Adding styles for specific addon


sl_header (Type: Append-Return)

  • Below store locator interface's search form, but above map. Make sure to print output: JS, HTML, etc
  • Example Usage: Adding additional map search form items (dropdown lists, checkboxes, etc) that provide front-end user with additional options, filters for map display


sl_addon_admin_scripts (Type: Append)

  • Adds JS, CSS needed to run / control addon in the admin area
  • Example Usage: Insert functionality for addons that work with the admin area


sl_mgmt_bar_links (Type: Select)

  • Add links to perform a function on locations
  • Example Usage: Add links for exporting locations


sl_mgmt_bar_form (Type: Select)

  • Add form elements to perform a function on locations
  • Example Usage: Tagging locations, bulk updating different fields for locations


sl_admin_form_post (Type: Append)

  • Executes anytime a form is submitted in the admin area with a method of 'post'
  • Example Usage: Create db table(s) necessary to use addon that is during the addon's validation


sl_single_location_edit (Type: Select)

  • On 'Manage Locations' admin page, when editing 1 location, allows for modification of location properties
  • Example Usage: Adding an map next to an individual location in edit mode to see its precise location


sl_top_nav_links (Type: Append)

  • Adds navigation tab(s) and corresponding sub-navigational links
  • Example Usage: Adding new tabs for addons that need additional space in the Store Locator admin


sl_define_columns (Type: Append)

  • Manipulate the '$sl_column_titles', '$sl_normal_columns', '$sl_omitted_columns', '$sl_xml_columns', $sl_categorization_columns' global variables for a specific custom field (column) using the 'sl_manage_column_views()' PHP function (more in "Functions (PHP)" section)
  • Example Usage: Label a newly created custom field, such as sl_category, as 'Category' and make it part of the normal view on 'Manage Locations' by using sl_manage_column_views("sl_category", "Category", 1, 0, 1) and then placing this function within another function that is hooked to the 'sl_define_columns' hook


sl_add_location_fields (Type: Append)

  • For "Add Locations" page, it adds form fields
  • Example Usage: Can be used by custom field manager, for example, to allow for users to input data into custom fields when adding a location


sl_edit_location_fields (Type: Append)

  • For "Manage Locations" page when editing an individual location, shows custom fields
  • Example Usage: Can be used be custom field manager, for example, to show data from custom fields for a specific location, so that it can be updated


sl_add_location_forms (Type: Append)

  • For "Add Locations" section of the admin, use this hook to create forms that will allow users to submit locations in different ways in addition to the default form for adding locations
  • Example Usage: Used to create the CSV import form, Database import form, etc


sl_admin_data (Type: Append)

  • Allows for adding arbitrary data, text, html to each page of the admin interface, directly below top navigation
  • Example usage: Use to create form with hidden fields that contain data that can be accessed by javascript in your addon's code


sl_update_activation_keys (Type: Append)

  • Executes when activation key(s) are being validated on addons' settings page
  • Example Usage: Create db table necessary to use addon that is being validated and/or submit initial settings needed by addon to Store Locator settings table


sl_xml_query (Type: Append)

  • Adds clauses in order to modify DB SQL query to retrieve locations in Store Locator's XML. Can modify the global variables $sl_param_where_clause, $sl_param_order_clause, and $sl_param_having_clause


sl_template_convert (Type: Append)

  • Use this in order to define additional filters on the '$sl_template_data' variable that holds a HTML & template shortcode that is being filtered when passing a template file into the sl_template_convert() function


sl_admin_notices (Type: Append)

  • Use to display admin notices on Store Locator admin pages, underneath the horizontal navigation bar


sl_admin_toolbar_filter (Type: Append)

  • Use to add new top-level Store Locator admin page link(s) to the Store Locator toolbar menu (must link to valid admin page(s), created by WordPress's 'add_submenu_page()' function).


sl_mapdesigner_options (Type: Append)

  • Use to add to / modify the $sl_mdo global array containing all of map options & features shown on the MapDesigner settings page


sl_menu_pages_filter (Type: Append)

  • Use to add page links to Store Locator's main navigation in WordPress's admin side menu (uses WP's 'add_menu_page()' & 'add_submenu_page()' functions)


sl_nav_buttons_right (Type: Append)

  • Use for the display of HTML buttons (or any HTML desired) floating to the right side within Store Locator's top sub-navigation tier


sl_search_button (Type: Append)

  • Use to modify the Store Locator interface's search button properties, such as 'type', 'src', 'class', 'style', 'onclick', 'mousedown', 'mouseover', etc.


sl_where_clause_filter (Type: Append)

  • Use to modify the 'WHERE' portion of the clause that determines which locations appear within a certain view on Store Locator > Locations > Manage page


Hooks (Javascript)

start_sl_load (Type: JS)

  • Start of sl_load function, but after sl_geocoder, sl_map, and sl_info_window objects are created


end_sl_load (Type: JS)

  • End of sl_load function, but after map tiles are loaded -- triggered by Google Maps' "tilesloaded" event


end_retrieveData (Type: JS)

  • Right after XML of location data retrieval is completed


start_searchLocations (Type: JS)

  • Start of the searchLocations function


end_searchLocations (Type: JS)

  • End of the searchLocations function


start_searchLocationsNear (Type: JS)

  • Start of the searchLocationsNear function


end_searchLocationsNear (Type: JS)

  • End of the searchLocations function


start_createMarker (Type: JS)

  • Start of createMarker function


end_createMarker (Type: JS)

  • End of createMarker function


start_createSidebarEntry (Type: JS)

  • Start of createSidebarEntry function


end_createSidebarEntry (Type: JS)

  • End of createSidebarEntry function


sl_details_filter (Type: JS | Params: sl_details)

  • Useful javascript function that allows you update the elements stored in the important JS variable 'sl_details', which is an array

Note: Avoiding Un-ending Loops

  • Javascript (JS) Functions can be referenced in hooks. Note, how to avoid creating an unending loop when referencing JS functions:
  • Important: You cannot make a reference to a function within a JS hook that references that same function, otherwise you will create an unending recursive loop of execution (For example, a function hooked onto 'end_createMarker' should not call createMarker() inside that particular function')
  • Secondly, for the 'end_retrieveData' hook, you cannot reference the functions 'searchLocations()' or 'searchLocationsNear()', as both of these function execute 'retrieveData' -- similiarly, an unending loop will occur.


Functions (PHP)

sl_data($setting_name, $mode="get", $setting_value="")

  • $setting_name (required) -- name of setting as it should be stored and retrieved from the Store Locator's settings table
  • $mode (optional || default: "get" || options: "get", "add", "update", "delete") -- database function that should be performed. Leave blank to retrieve value store under $setting_name label
  • $setting_value (optional) -- only needed for "add" & "update" modes. Stores this value under the $setting_name label in settings table


  • Starting in Store Locator 2.0 all data is now stored in the Store Locator's own settings table using sl_data(), which is similar to {get/add/update/delete}_option() functions as follows:
  • get_option($setting_name) --> sl_data($setting_name)
  • add_option($setting_name, $setting_value) --> sl_data($setting_name, "add", $setting_value)
  • update_option($setting_name, $setting_value) --> sl_data($setting_name, "update", $setting_value)
  • delete_option($setting_name) --> sl_data($setting_name, "delete")


sl_add_db_field($field_name, $extra_field_info="VARCHAR(255) NULL DEFAULT NULL")

  • $field_name (required) -- custom field as you want it to be labeled in the store locator database (e.g. 'sl_category')
  • $extra_field_info (optional || default: "VARCHAR(255) NULL DEFAULT NULL") -- define additional properties when creating a custom field


  • Use this function to update the main Store Locator database table with a new (custom) field, for example "sl_category" to store additional data needed for your addon to work properly
  • A notification message stating that the new field has been successfully add will be displayed on success (function always performs check to see if field already exists)


sl_remove_db_field($field_name)

  • $field_name (required) -- custom field as you want removed (default fields cannot be removed)


sl_manage_column_views($db_label, $readable_label, $is_sl_normal_column=false, $is_sl_omitted_column=false, $is_sl_xml_column=true, $is_sl_categorization_column=false)

  • $db_label (required) -- Database label (example: "sl_category")
  • $readable_label (required) -- Human readable label that you want showing up throughout the Store Locator interface (example: "Category")
  • $is_sl_normal_column (optional || default: false || options: true, false) -- Whether or not you want a custom field to show up in the "normal" (non-expanded) 'Manage Locations' admin view (if true, takes precedence over '$is_sl_omitted_column')
  • $is_sl_omitted_column (optional || default: false || options: true, false) -- If true, this custom field will not show up in the 'Manage Locations' admin view at all -- good for custom fields that hold meta information, but don't need to be displayed/searched for (ignored if '$is_sl_normal_column' is set to true)
  • $is_sl_xml_column (optional || default: true || options: true, false) -- Determines whether or not you want the custom field to show up as an attribute in the location XML generated during a Store Locator search, which would also allow the custom field data to be displayed on the Store Locator map's info windows and search results (attribute format within the XML is: $db_label="{value from database}". Always shows in location XML if '$is_sl_categorization_colum' is true).
  • $is_sl_categorization_column (optional || default: false || options: true, false) -- If true, this custom field will be used as the field from which data is used to categorize locations, meaning values in this field will determine which icon and which category a specific location will be defined under (if true, takes precendence over '$is_sl_xml_column' and will always put data in location XML).


  • Use this function to fully define the attributes of a new (custom) field throughout the Store Locator plugin, both admin and user-facing aspects


sl_template_convert($template_file, $restrict_tags)

  • $template_file (required) -- Full path to the template file representing the layout of page
  • $restrict_tags (required || options: true, false) -- If true, only allow the following tags: div, br, p, span, u, i, strong, b, em, center, table, tr, td, tbody, thead, input, tfoot, a, blockquote, colgroup, font, h1, h2, h3, h4, h5, h6, hr, li, ul, ol, pre, small, sub, sup, img
  • Use this function to filter a file using template shortcode if you want to create a template for your addon to use. Modify how your template is filtered by using the "sl_template_convert" hook


sl_show_custom_fields()

  • Display all custom fields that are created by 'sl_add_db_field()'. This function displays these custom fields via the 'sl_edit_location_fields' hook.


Global Variables (PHP)

$sl_columns (multi-dim array)

  • The name of each of the fields in the Store Locator database. Use "sl_columns[n]['Field']" to retrieve field, where "n" is the numerical array index (sample values under the 'Field' key: "sl_city", "sl_state", etc.)


$sl_all_columns (array)

  • Similar to $sl_columns, however only contains field names, and is 1-dimension, numerically indexed array ($sl_all_columns[0]='sl_id', $sl_all_columns[1]='sl_store', etc.). Easier to loop through.


$sl_column_titles (array)

  • User-defined labels/titles given to each field, to be more human-readable (sample values: "Street (Line 2)" is used for "sl_address2" by default)


$sl_omitted_columns (array)

  • Use this array to hide display of specific columns, for example, when doing an import. Use "in_array()" PHP function to check against this array when looping through the "sl_columns" array (by default, 'sl_id' & 'sl_neat_title' are part of this array)


$sl_normal_columns (array)

  • Columns that are shown in a normal (as opposed to an expanded) view. Use "in_array()" PHP function to check against this array when looping through the "sl_columns" array (by default, 'sl_id', 'sl_store', 'sl_address', 'sl_address2', 'sl_city', 'sl_state', 'sl_zip', 'sl_tags', 'sl_latitude', 'sl_longitude' are all part of this array)


$sl_xml_columns (array)

  • Columns that you would like to add to the default fields that in the XML generated during a search (by default, this array is empty)


$sl_categorization_columns (array)

  • Columns that you would like used to define the category of each location. Only zeroeth entry is used. Zeroeth entry determined by priority given to hook functions when adding custom field to this array using 'sl_manage_column_views()' function and 'sl_define_columns' hook


$sl_template_data (string)

  • When using the sl_template_convert() function, this variable holds all the template's HTML & shortcode. Modifying this variable within your own function that hooks onto the 'sl_template_convert' hook (which is inside the sl_template_convert() function) allows you to create filtering rules for your templating system. Once these filter rules have been created, you can store the HTML (with all shortcodes translated) back to a variable of your choice using $variable=sl_template_convert($template_file, $restrict_tags) (see more about function above)


$sl_top_nav_hash (array)

  • 1-dimensional, numerically indexed array of the names of all top-level pages. By default, it's value is array(0=>'locations', 1=>'mapdesigner'). Add elements using the 'sl_top_nav_links' hook.


$sl_top_nav_links (array)

  • Top-level navigation. These pages must correspond to WordPress admin pages to be viewed / accessed.
  • Array format: $sl_top_nav_links[ {url of page} ]=[ {human-readable title of page} ]; Add elements using the 'sl_top_nav_links' hook.

$sl_top_nav_sub_links (array)

  • Sub-navigation underneath top-level navigation.
  • Format of array: $sl_top_nav_sub_links[ {$sl_top_nav_hash[n]} ][ {human-readable title of page} ]={url of page}; Note, the URL value of the first element of this array should equal the URL value of the key of the corresponding top-navigation array that it is associated with. Sub-navigation array only needed if there are 2 or more sub-links associated with a top-level navigation page. Add elements using the 'sl_top_nav_links' hook.

$sl_mdo (multi-dimensional array)

  • field_name (required) -- name of the key stored in the $sl_vars array when saving the value


  • default (required) -- initial value field is set to


  • input_zone (required) -- the area of MapDesigner setting page where new option will appear (available values [as of v3.74] - "defaults", "labels", "dimensions", "design")


  • output_zone (required) -- the area of Store Locator's functionality your option affects (available values [as of v3.74] - "sl_dyn_js", "sl_template", "sl_xml", "sl_head_scripts")


  • label (required) -- Description of option in MapDesigner settings


  • input_template (required) -- HTML of the form element representing the new option


$sl_param_where_clause (string)

  • Contains WHERE clause for displaying Store Locator search results


$sl_param_order_clause (string)

  • Contains ORDER clause for displaying Store Locator search results


$sl_param_having_clause (string)

  • Contains HAVING clause for displaying Store Locator search results


Global Variables (Javascript)

Default

sl_map


sl_geocoder


sl_info_window


sl_marker_array (array)


sl_marker_type

  • The category slug associated with a single location


sl_marker_categorization_field

  • The field that is designated as the field which will define the sl_marker_type.
  • Example: 'sl_marker_type' could equal 'house' for one location and 'apartment' for another location, but 'sl_marker_categorization_field' would be defined as 'sl_category' because this is the field within in the Store Locator database table that holds the values of 'house' and 'apartment' for these specific locations.


sl_details (array)

  • The array which carries all database information from the XML into the Javascript functions that build the map results. All database fields that show up in the XML are part of this array, e.g. sl_details['sl_store'], sl_details['sl_city'], etc. (both can also be retrieve using sl_details.sl_store & sl_details.sl_city, etc.). Also include non-database elements such as 'fullAddress', 'homeAddress', 'point', & 'sl_distance'. All database field elements can be modified via the 'sl_details_filter' JS hook in which one can use an if-statement to update the output of a specific element


Can Be Created

sl_icons (array)

  • Optional 2-D array which can be created. Format should be:
sl_icons={ 

    {category_tag_slug}: {

        url: '{icon_url}', 

        name: '{icon_label}'

    },

    {category_tag_slug #2}: { 

        url: '{icon_url #2}', 

        name: '{icon_label #2}'

    },

    .

    .

    .

    {category_tag_slug #n}: { 

        url: '{icon_url #n}', 

        name: '{icon_label #n}'

    }

};
    


sl_xml_properties_array (array)

  • when new fields are added to '$sl_xml_columns' array in PHP (e.g. $sl_xml_columns[]='sl_category'), 'sl_xml_properties_array' is automatically created in the javascript to be added to the outputted xml for each search.


sl_mvc_objects (multi-dimensional array)

  • Optional array which can pass standard Google Maps MVC objects to your Store Locator map. Example:
sl_mvc_objects['type']=[

    google.maps.Polygon,

    google.maps.TrafficLayer,

    google.maps.KmlLayer

];

sl_mvc_objects['options']=[

    {Polygon object},

    '', //blank -- none need for Traffic layer specs

    {KML object}

];
    

Special Notes for Different Pages

  • On "Manage Locations", if your addon manually updates the coordinates (latitude & longitude) of a location, make sure to add a hidden field with name or 'no_geocode' and value of '1'. This will prevent geocoding to occur on submission of the new address, so that the manual coordinate changes will be preserved.


  • Sidenote: Note that passing 'no_geocoding' value 1 can be done for any addon needing to avoid geocoding processes on Manage Locations page, even if it's not manually updating coordinates
  • On "Manage Locations", if using the "sl_single_location_edit" hook & adding custom form field(s) to be submitted, only append "-{id number of location}" to the "name" property of these custom form fields that have a name that matches a field in the store_locator DB. (e.g. "sl_category-4" would be the "name" property of a location with the ID of "4". Append id number usually by adding "-$_GET['edit']" to your code.
  • To force all javascript in the <HEAD> HTML tag to show up (in cases where your page doesn't use the [store-locator] shortcode):
  • Create an empty function "show_sl_scripts()". Scripts will be shown on any page where this function exists: if (!function_exists("show_sl_scripts")){ function show_sl_scripts() {} }

Installation

  • Note: All addons marked v2.0 and later are now fully WordPress plugins and can be installed as such
  1. Upload the Developer Console zip file (downloaded from your account page) via WP Admin > Plugins > Add New > click 'Upload Plugin' button
  2. Once upload is complete, turn on the addon using 'Activate' button (can also be done on WP Admin > Plugins page)
  3. Once turned on, you can validate the addon by submitting your purchase key under WP Admin > Store Locator > Addons > Settings
  4. Now you can then manage the addon's settings under WP Admin > Store Locator > Addons > Settings > Location Pages

(Further usage tips & instructions included with addon)


«Back List of Addons | Purchase Addons Now»