BCT Mapping

Version

1.0

Description

This plugin adds Bay Circuit Trail specific data to an interactive Google Map using WordPress functionality to store data and integrate necessary mapping tools into WordPress pages, and the Google Maps v3 Javascript API to display the data. 

Requirements

PHP 7+
MySQL 5.6+
WordPress 4.8.2+
Google Maps API Key
SSL Certificate (required for “find me” technology)

Licensing

The development of this plugin for AMC, by Ternstyle LLC, will be considered “Work Made for Hire.” To the extent that any portion of the Work constitutes a work protectable under the Copyright Law of the United States (the “Copyright Law”), AMC and Ternstyle LLC agree that any such portion of the Work has been specially ordered and commissioned by AMC and shall be considered a “work made for hire” as such term is used and defined in the Copyright Law. Accordingly, AMC shall be considered the “author” of such portion of the Work and the sole and exclusive owner throughout the world of copyright therein.

In the event this plugin, developed for AMC by Ternstyle LLC, includes open source or proprietary code that cannot be owned or copyrighted by AMC, the appropriate licenses will be included within the application. Any licenses for proprietary code developed by Ternstyle LLC shall be considered executed between Ternstyle LLC and AMC and are non-transferrable.

Dependencies

iLightbox

https://codecanyon.net/item/ilightbox-revolutionary-lightbox-plugin/3716175

This lightbox plugin is required for displaying parking and point of interest data upon click of Google Map marker.

Licensure: A license has been purchased for use in this project.

Markerclusterer

https://github.com/googlemaps/v3-utility-library/tree/master/markerclusterer

This JavaScript functionality is used to cluster Google Map markers when zoomed out.

Licensure: Open Source

PHPExcel

https://github.com/PHPOffice/PHPExcel

This set of PHP classes parses Microsoft Excel data. It’s used in the plugin to parse parking lot and point of interest data from an Excel spreadsheet prior to import.

Licensure: GNU Lesser General Public License

FontAwesome

An icon font.

Licensure: SIL OFL 1.1

fileClass

A PHP class for dealing with files and directories.

Licensure: License included in plugin at ternstyle-licensing.rtf

parseForm

A PHP class for parsing submitted form data.

Licensure: License included in plugin at ternstyle-licensing.rtf

select

A PHP class for printing HTML select elements from PHP arrays.

Licensure: License included in plugin at ternstyle-licensing.rtf

ternWP

A PHP class for performing basic WordPress functions for plugins.

Licensure: License included in plugin at ternstyle-licensing.rtf

xls_import

A PHP base class for parsing and importing Microsoft Excel spreadsheet data as WordPress posts.

Licensure: License included in plugin at ternstyle-licensing.rtf

tern_errors

A PHP class for printing administrative errors and alters.

Licensure: License included in plugin at ternstyle-licensing.rtf

Directory / File Structure

/bct-mapping
	/admin
		/class
			bct-import-points.php
			bct-import.php
		/css
			style.css
		/js
			errors.js
			import.js
		/views
			import-kmz.php
			import-points.php
			import.php
			settings.php
		import-kmz.php
		import-points.php
		import.php
		settings.php
	/class
		file.php
		forms.php
		select.php
		wordpress.php
		xls-import.php
	/data
		trail.kmz
	/includes
		bct-map.php
		errors.php
		menus.php
		post_types.php
		scripts.php
	/public
		/css
			style.css
		/images
			parking-pin.png
			point-pin.png
		/js
			scripts.js
		/views
			map.php
		shortcode.php
	/tools
		iLightBox-2.2.0
		markerclusterer
		PHPExcel
	bct-mapping.php
	Documentation.rtf

Usage

Map Display

WordPress has two primary post types, Pages and Posts. In addition, WordPress has built-in functionality for creating custom post types. With the use of WordPress’ shortcode functionality, the BCT Map can be displayed on any page, post, or custom post type. You can read about shortcode here: https://codex.wordpress.org/Shortcode

Shortcode is a macro, comprised of a name and key/value pairs, encompassed by brackets, which is processed by WordPress when rendering a page or post. The BCT Mapping shortcode requires no key/value specifications as of version 1.0.

To display the BCT map on any page, post, or custom post type, use the following shortcode:

[bct-map]

Settings

Page: /wp-admin/admin.php?page=bct-settings

This plugin has required settings necessary for the mapping functionality.

To edit settings:

	1.	Log into WordPress
	2.	In the WordPress administrative left-hand-side navigation, click the “Settings” sub-navigation element of the “BCT Mapping” menu

List of settings:

Google API Key (string) - This setting is required for the use of the Google Maps Javascript v3 API. It is publicly visible, as it is appended to the “src” specification of the <script> call for the Google Maps JavaScript API. This value can be generated in the Google API Console, and should be restricted by domain to prevent its pirated use on other sites.

Import of Map Data

NOTE: The KML responsible for displaying the trail data resides at /data/trail.kmz within the plugin. It is paramount the location and name of the file remain the same. This file can be uploaded via the “Import Trail KMZ” page of the plugin.

One of the key features of the BCT Mapping plugin is the bulk import of data. This bulk import saves time and allows AMC to store map data in Microsoft Excel spreadsheets, to be used in multiple applications outside the use of the BCT website. The ubiquitousness of Excel allows any staff member of AMC to maintain trail data in a single format without having to learn WordPress or be trained in the BCT site. One caveat being, an import will need to take place after any change of data.

The import does, however, update data for data points which have already been imported, effectively overwriting altered data and preventing the import of duplicate data. This overwrite occurs based on the name of the data point.

Import Trail KMZ

Page: /wp-admin/admin.php?page=bct-import-kmz

On this page, there is a field for upload of the trail KMZ file. Simply, select the file and click the “Import” button. Allow for the import to complete. The file is uploaded to the server and moved to the plugin’s /data/ directory with the name trail.kmz.

Importing Parking Data

Page: /wp-admin/admin.php?page=bct-import

On this page, there is a field for upload of the parking data Excel spreadsheet. Simply, select the file and click the “Import” button. Allow for the import to complete.

It is paramount the spreadsheet worksheet and columns are recognized by the plugin. The title of the worksheet must be “Parking.” Any columns that deviate from the following specification will be ignored by the plugin. Each column will be imported as post meta in the wp_postmeta table and can be accessed and altered using the standard WordPress post meta functions, i.e. get_post_meta(). A unique identifier is used to find parking data which has already been imported. 

The spreadsheet columns should be as follow:

	1.	Type		(string)	key: type
	2.	Surface	(string)	key: surface
	3.	Spaces	(int)		key: spaces
	4.	Seasonal	(string)	key: seasonal
	5.	Landmark_I	(string)	key: landmark
	6.	Town		(string)	key: town
	7.	Region	(int)		key: region
	8.	MAP		(int)		key: map_number
	9.	Location	(string)	key: location			unique identifier
	10.	Restrictions	(string)	key: restrictions
	11.	Fee		(string)	key: fee
	12.	BCT_status	(string)	key: status
	13.	Landowner	(string)	key: landowner
	14.	Manager	(string)	key: manager
	15.	Street_loc	(string)	key: street_location
	16.	Land_unit	(string)	key: land_unit
	17.	POINT_X	(float)		key: lng
	18.	POINT_Y	(float)		key: lat

Importing Point of Interest Data

Page: /wp-admin/admin.php?page=bct-import-points

On this page, there is a field for upload of the point of interest data Excel spreadsheet. Simply, select the file and click the “Import” button. Allow for the import to complete.

It is paramount the spreadsheet worksheet and columns are recognized by the plugin. The title of the worksheet must be “Points.” Any columns that deviate from the following specification will be ignored by the plugin. Each column will be imported as post meta in the wp_postmeta table and can be accessed and altered using the standard WordPress post meta functions, i.e. get_post_meta(). A unique identifier is used to find point of interest data which has already been imported.

The spreadsheet columns should be as follow:

	1.	Type		(string)	key: type
	2.	View_Beari	(string)	key: view-bearing
	3.	View_angle	(int)		key: view-angle
	4.	Name		(string)	key: name			unique identifier
	5.	Comment	(string)	key: comment
	6.	POINT_X	(float)		key: lng
	7.	POINT_Y	(float)		key: lat
	8.	Info		(string)	key: description

Specification

/bct-mapping.php

This file instantiates the plugin. The commented protocol in the beginning of the file informs WordPress that the files in this directory comprise a plugin, version, and describe the plugin.

 Purpose:

	1.	Instantiate the plugin
	2.	Define global variables
	3.	Include all necessary plugin files
	4.	Initialize the plugin settings

Specification:

function BCT_init(  )

Retrieve the plugin settings from the database and make them available globally. 

/admin/class/bct-import-points.php

Purpose:

	1.	Extends the base class xls_import and adds functions specific for importing points of interest.

Specification:

class BCT_import_points( uploaded_spreadsheet_file_location )

variable point_of_interest_columns

Contains specifications which map Excel spreadsheet columns with corresponding database fields. 

function import_points(  )

Starts the import of the Excel spreadsheet.

function get_item_points(  )

Finds the post in the WordPress database which has just been imported.

/admin/class/bct-import.php

Purpose:

	1.	Extends the base class xls_import and adds functions specific for importing parking data.

Specification:

class BCT_import( uploaded_spreadsheet_file_location )

variable parking_lot_columns

Contains specifications which map Excel spreadsheet columns with corresponding database fields. 

function import_parking(  )

Starts the import of the Excel spreadsheet.

function get_item_parking(  )

Finds the post in the WordPress database which has just been imported.

/admin/import-points.php

Purpose:

	1.	Display the administrative import page for importing points of interest.
	2.	Process the imported file and trigger the import

Specification:

function BCT_parse_spreadsheet_points(  )

Validate post data and trigger import.

function BCT_import_points(  )

Display the administrative import page for importing points of interest.

/admin/import.php

Purpose:

	1.	Display the administrative import page for importing parking data.
	2.	Process the imported file and trigger the import

Specification:

function BCT_parse_spreadsheet(  )

Validate post data and trigger import.

function BCT_import(  )

Display the administrative import page for importing parking data.

/admin/settings.php

Purpose:

	1.	Display the administrative settings page
	2.	Process the posted settings

Specification:

function BCT_settings_actions(  )

Validate and save post data.

function BCT_settings(  )

Display the administrative settings page.

/includes/bct-map.php

This class is used when processing the shortcode and displaying the map.

Purpose:

	1.	Retrieve and process map data for display in the map

Specification:

class BCT_map(  )

variable data

Store both parking and point of interest data.

variable point_of_interest_columns

Contains specifications which map Excel spreadsheet columns with corresponding database fields.

variable parking_lot_columns

Contains specifications which map Excel spreadsheet columns with corresponding database fields.

function get_data(  )

Run functions for retrieving both parking and point of interest data.

function prepare_data( name_of_data_to_prepare, data_array_to_prepare, data_column_array )

Ensure the map data is in the proper format. Place the data in an optimized array for output to JavaScript.

function filter_data(  )

Ensure the map data is in the proper format. This function is used but the prepare_data function.

function get_parking(  )

Retrieve all parking data from the database.

function prepare_parking_data(  )

Run the prepare_data function for parking specific data.

function get_point(  )

Retrieve all point of interest data from the database.

function prepare_point_data(  )

Run the prepare_data function for point of interest specific data.

/includes/menus.php

Purpose:

	1.	Add administrative menus for the plugin

Specification:

function BCT_menu(  )

Add the menu and the submenu items for the plugin.

	1.	BCT Mapping
	⁃	Settings
	⁃	Import Parking Lots
	⁃	Import Points of Interest

/includes/post_types.php

Purpose:

	1.	Register the necessary post types for storing parking lot and point of interest data

Specification:

function BCT_register_post_types(  )

Uses built-in WordPress functionality for creating custom post types for the following post types:

	1.	Parking Lots
	2.	Points of Interest

/includes/scripts.php

Purpose:

	1.	Register all stylesheets for use in the plugin
	2.	Register all JavaScript files for use in the plugin
	3.	Print necessary global JavaScript variables

Specification:

function BCT_register_styles(  )

Register all stylesheets for use in the plugin. Also enqueues bct-admin if we’re viewing an administrative page.

	1.	bct-admin - Used to style administrative aspects of the plugin
	2.	ilightbox - Specific to the Lightbox plugin
	3.	font-awesome - Open source icon font used in map controls
	4.	bct-style - Used to style front-end aspects of the plugin

function BCT_register_scripts(  )

Register all JavaScripts for use in the plugin.

	1.	ilightbox - Specific to the Lightbox plugin
	2.	google-maps - Google Maps Javascript v3 API
	3.	markerclusterer - Used to cluster map markers when zoomed out
	4.	bct-errors - Used to display errors
	5.	bct-scripts - Runs all the front-end JavaScript, including the map

function BCT_js(  )

Print necessary global JavaScript variables to the front-end HTML output.

/public/shortcode.php

Purpose:

	1.	Register bct-map shortcode
	2.	Compile map HTML
	3.	Enqueue necessary scripts
	4.	Enqueue necessary styles

Specification:

function BCT_show_map( array_of_options )

This function compiles all necessary HTML, JavaScript, and map data for display of the map on the front-end and returns it as the replacement for the shortcode macro. It employs the /includes/bct-map.php functions for retrieval and preparation of map data.

As of version 1, no parameters are necessary or used for this function.

/public/js/scripts.js

This file runs all the mapping functionality on the front-end.

Purpose:

	1.	Display the interactive Google Map
	2.	Display KML information
	3.	Set map boundaries
	4.	“Find Me” functionality
	5.	Display parking data
	6.	Display point of interest data
	7.	Show comprehensive information in a lightbox

Specification:

variable bct_map_data (json)

This variable stores all the map parking and point of interest information. It is created and published to the HTML output by the shortcode function in /public/shortcode.php. It’s mentioned here because this is the file that uses this data and refers to this variable.

It is formatted like so:

var bct_map_data = {
	parking : [  ],
	point :	[  ]
};

variable bct_map_style

Store styling options for the map. Turns off administrative, poi, water, and road labels.

variable bct_map

An object of google.maps.Map. This is the instantiated variable of the Google Maps map.

variable trail

An object of google.maps.KmlLayer. This is the instantiated variable of the trail data KML layer.

variable bounds

An object of google.maps.LatLngBounds. This variable changes the map viewport when parking and point of interest data is created and added to the map for the first time. It essentially centers the map with all markers fitting within the viewport. 

variable parking_lot_columns

An array of parking fields to be displayed in lightbox when a parking marker is clicked within the map.

variable parking_lots

An array of google.maps.Marker objects. This variable is compiled while iterating through parking lots and instantiating google.maps.Marker objects.

variable point_of_interest_columns

An array of point of interest fields to be displayed in lightbox when a point marker is clicked within the map.

variable point_of_interest

An array of google.maps.Marker objects. This variable is compiled while iterating through points of interest and instantiating google.maps.Marker objects.

function reset_bounds(  )

Sets the bounds variable to a new object of google.maps.LatLngBounds.

function extend_bounds( google.maps.LatLng )

Extends the bounds of the map to include a coordinate specified by an object google.maps.LatLng.

function set_bounds(  )

Apply the boundary stored in the bounds variable to the map, effectively repainting the viewport to include all coordinates stored in the bounds variable.

function find_me( google.maps.LatLng )

Sets the center of the map to the location specified. This function is run upon clicking the “Find Me” button. Upon clicking the button a function is run to determine the user’s location. This function only works if the website is employing the https:// protocol. Without it, browsers determine sharing of location data to be risky and determining a user’s location will fail.

function find_me_fail(  )

Run when a user’s location cannot be found. An error is displayed in a lightbox.

function create_parking(  )

Iterates through all parking data and instantiates google.maps.Marker objects.

function show_parking(  )

Display all parking markers in the map.

function hide_parking(  )

Hide all parking markers in the map.

function bind_parking(  )

Bind all parking markers with a click event for displaying pertinent marker information. In addition, a zoom event is bound to the map for displaying/hiding parking based on map zoom level.

function create_point(  )

Iterates through all point of interest data and instantiates google.maps.Marker objects. It also adds all the markers to clustering so the map doesn’t look like a total mess.

function show_point(  )

Display all point of interest markers in the map.

function hide_parking(  )

Hide all point of interest markers in the map.

function bind_parking(  )

Bind all point of interest markers with a click event for displaying pertinent marker information. In addition, the “Point of Interest” control above the map is bound to show/hide point of interest markers.

function display_error( error_string )

Show specified errors in a  lightbox.