This repository contains the source code maintained for used on the site currently at: http://roger.navevent.co.nz/orienteering-events-map/
This open source project welcomes contributions and suggestions. Please refer to the Roadmap and Contributions section below.
The "Auckland Orienteering Events" site provides an interactive display of upcoming orienteering events in the Auckland region and brief details about the events.
Interactive text search functionality is provided within the list of events to assist in finding events on a certain day of the week, upcoming month of the year, or within the region of interest.
For each event, details on the date, registration location, start times and times are provided along with additional assistance identifying the closest train/bus stations.
Adding an individual event into your personal Google calendar is easy through a button on each event.
This repository contains Roger Woodroofe's completed Map Neighbourhood project for the Udacity Front End Web Developer Nanodegree. More information on the project requirements are available at: Udacity Front End Web Developer Nanodegree overview.
Orienteering is a map based sport and recreational activity.
Orienteers use a detailed orienteering map that uses an international mapping standard of symbols to describe the terrain and how easy it is to traverse (i.e. get from point A to point B). Each course map also identifies the locations course participants need to visit to successfully complete the course they have selected.
Walk, Jog, or Run. Easy through to very challenging navigation. Individuals or go as a group. It's up to the participants. Orienteering offers an activity that exercises the body and mind at the same time - and top athletes need to manage the balance between both. Suitable for all ages and most abilities, events can be either by foot, mountain-bike, ski's or trail (by vision alone). It's an excellent family based activity as all ages can usually participate in an event during the same time and area.
Third Party Requirements:
- KnockoutJS - for event list management
- Material Design Lite - Page and component styles
- JQuery UI - AJAX services and date conversion functionality
- php-date-formatter.js script - provides date string formatting
Additional functionality requires:
- Google Calendar API - allows user to add event to Calendar
- Auckland Transport (AT) API - allows user to see list of local bus/train stops
Note: Copyright and license text of third party modules are included in their source code.
How to Use This Project
/ contains build configuration files and this
/src/ contains source files and
/dist/ contains the gulp generated optimised files ready for use.
/docs contains function documentation generated from the source code.
A. Initial Development Structure Setup
- (optional) Fork or clone the repository on GitHub.
- Use git to clone the repository to your local system.
git clone https://github.com/rogyw/ufend-P8-neighbourhood-map.git
- Install or update to the latest version of node.js and npm.
- Open your local console and change the current directory to the project root folder (location of
- Run the command
npm installto install required gulp modules and jsDoc as defined in included
- Run the command
bower installto install required bower dependancies.
- Obtain API Keys and update configuration settings in source as outlined in section below.
- To refresh the contents of
distfolder use the command
gulp rebuild. The rebuild will delete the old dist folder and rebuild based on current source files. Note: Using the command
gulpwill initiate the default gulp watch on selected source folders.
- Copy files from
distto your web hosting account or alternatively to deploy the contents of
distfolder to your live
gh-pagesfor the repostitory on Github use
- Visit your site to test it works!
B. Configuration of Installation
This repository uses several APIs which require an appropriate API Key to enable the full use of this code. Note: The keys included in this repository may not be valid or may be limited to use from specific domain names.
- Google Maps API
- Obtain a Google Maps Key
- Update the following line in the
/src/index.htmlto specify your Google Maps Key. Make sure you leave the double quotation mark following the end of the key.
<script defer src="https://maps.googleapis.com/maps/api/js?callback=initMap&key=AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsT" async></script>
- Google Calendar
- Visit the Google Developer Console for Google APIs, https://console.developers.google.com
- Create Credentials for Google OAuth 2.0 and enable the Google Calendar API. Refer to current Google API Help for further instructions.
- Edit and save the
src/gcalendar.jsfile to set the constant
GCALENDAR_CLIENT_IDto your personal Google API credentials key. e.g.
var GCALENDAR_CLIENT_ID = '0123456789012-abcdefghijklmnopqrstuvwxyz123456.apps.googleusercontent.com';
- Auckland Transport API
- Obtain your API Key by signing up for a development API Key at: https://api.at.govt.nz/registration/
- Edit and save the
src/app.jsfile to set the constant
API_ATAPI_SECRET_KEYto your personal Auckland Transport API account key. e.g.
var API_ATAPI_SECRET_KEY = "abcd1234-efgh5678-ijkl9012-mnop3456";
C. Running a Local Http Web Server
(Optional) If you do not currently have an http web server available:
HTTP/2 using simplehttp2server
To install simplehttp2server:
- Download the appropriate precompiled release of simplehttp2server for your system by visiting simplehttp2server Releases page on Github.
- (optional) If required, rename the downloaded file to the appropriate filename for your system. For example on Windows:
rename simplehttp2server_windows_amd64 simplehttp2server.exe
- Move the downloaded
simplehttp2serverfile into a folder included in your system path.
- Within a command line console, change current directory to the folder containing files to be served.
- At the command prompt, type
simplehttp2server. simplehttp2server will start and display the port number it is listening on.
- View the site at
https://localhost:5000/where 5000 is the
listening onport number.
- Further details available in the simplehttp2server README and the video - HTTP/2, Totally Tooling Tips.
- Make sure you use https:// with simplehttp2server as use of http:// will produce unexpected behaviour.
- A security warning will be displayed in your browser indicating the certificate is provided by an unknown authority.
HTTP/1 using Python simplehttpserver or Python http.server
Python provides the ability to easily serve a folder via an http web service on your local development computer for testing purposes.
- Download and install Python from https://www.python.org/downloads/.
- At the console command line prompt, change to the folder containing the set of files to be used.
cd /my/path/to/files/distNote: You can use either
/src/from the repository.
/dist/contains optimised files for production use. Section A above describes how to generate the
distset of files from the repository.
/src/contains the source files before optimisations which will be easier to use if you intend to view, edit, or debug the code.
- At the console command line prompt, type either:
- (Python 2)
python -m SimpleHTTPServer 8080or
- (Python 3)
python -m http.server 8080. This will start the service serving the current directories files as
- Open a web browser and view
Updating the docs folder
JSDocs is used to create the
docs folder documentation from the source jsdoc code comments. Further information is available at http://usejsdoc.org/. To create the docs, use the following commandline in the repository root folder:
jsdoc ./src/js -R ./README.md -P ./package.json -d ./docs
Optimisations to files in dist completed by Gulp
- gulp-cssnano - minify CSS files
- gulp-autoprefixer - auto-prefix CSS
- gulp-gh-pages - upload to gh-pages
- gulp-imagemin - reduce image sizes
- gulp-htmlmin - minify html files
- run-sequence, del - used for project building
version 2.0 Project Submission 2 - 8 July 2016
- fixes and code improvements
- increased use of Knockout.js
- removed infoBubble displayed on map and external dependancy
- add Material Design layout with scrollable tabs for event details
- add Material Design Icons for event tabs menu
- add customised link for event to Auckland Transport to assist with trip planning
- adds HTTPS / HTTP/2 support
- documentation updated
version 1.0 initial project submission
- initial submission
- Search and display of events in map
- Display selected event details in infoBubble on map
- Button to add event to Google Calendar
- API information from Auckland Transport
Roadmap and Contribution Requests
Features to be added in future releases:
- Add New Zealand wide orienteering events listings
- use OrienteeringNZ events listings RSS feed as information provider (use rsstojson)
- update OrienteeringNZ events RSS feed to include location information and other details
- add regional public transport support
- add additional filtering fields or options
- Only show upcoming events
- Provide date range filtering
- Add location based map centering to show events near user
- Add NZ permanent courses information
- add progressive web application support
- save event information for offline use
- add icon to homepage
- add splash page for homepage icon users
- Link to results after event
- Add locations of nearby Toilets/Public conveniences.
- Add local after-hours accident-and-medical-centres link
- Add international events information
Please add an issue on Github to suggest additional features or a pull request to contribute features.