Team Assignment 2
Run Challenge app
MCD4290 Trimester 2 2019
Due: Friday Week 11, 11:55PM Local Time
Worth: 24% of final mark

Aim

Your team will develop a location-aware app which allows the user to test themselves
running to random nearby locations and improve their overall fitness. Your app will
determine the user’s initial location and allow them to request a random location to run
to. As they run, the app will track their location and calculate the time, distance and
speed of the run. Users will then be able to compare runs and reattempt previous ones to
improve.

This assignment will require you to demonstrate an understanding of object orientation,
persistent storage, use of external APIs, as well as related of code style, documentation,
and principles of interface design.
Background
Your team, along with 23 others, have been flown to Osnea (a mid-msized pacific nation)
on behalf of the Osnean Institute of Sport (OIS), which trains famous athletes such as
“Fast-Terry Van Zanzebolt”, “Riley Quick”, “Fi Targoing” and “Mani Kays”. As part of a
tender process, they have tasked each team with developing a proof of concept app to
help their athletes train using their phones.

The best proof of concept app will result in further work for that team as they will be
tasked in developing and maintaining a full app that can be distributed to all those at OIS
to help runners and hurdlers prepare for upcoming events. If it is well received by their
athletes, OIS may also consider asking the winning organisation to make the app accessible
as a paid product via app stores for Android, Apple and Windows Phone.

What you are provided with
We have made available a skeleton version of the app. The skeleton provides you with
several HTML pages and associated JavaScript and CSS files representing the structure of
the app. You will need to implement the logic and functionality for each of these pages as
described below.

The app skeleton contains three web pages that utilise MDL for their interface:
● Runs List page (main index page)
● New Run page
● View Run page

A “Run” is a series of ordered points representing the path the user runs to reach their
destination.

In the app skeleton, these pages are mostly blank. They include sample entries only to
demonstrate how to navigate and pass information from one page to another. You may
modify these files as you like, however you should not change the file names.

The app skeleton contains a displayMessage function in the utility.js that you can use to
display toast messages.
What you need to do
This assignment consists of multiple tasks, including programming, documentation, and
use of software tools. For the programming tasks, we suggest you complete each step
together as a team before moving onto the next one. It is strongly recommended that you
practice pair programming rather than trying to split up the coding and attempting parts
individually.

You will need to communicate effectively with your team while working on the
assignment. Your use of Bitbucket, Asana, and Google Drive will affect your final marks on
this assignment and as with Assignment 1, your final marks will be scaled by your team
contribution as determined by CATME.

Finally, there will be a team “client” presentation as well as an individual interview on
your submitted code, both of which will occur during your week 12 practical class.

Getting started
1. One team member should create an “assignment2” directory with the necessary
initial directory structure in your team’s repository by committing the provided
skeleton code (see the Skeleton code and the “Submission” section below).
2. One of your team members should set up an API key for Mapbox attached to a team
Google account (if you didn’t do this already as part of the Week 6 prac exercise).
3. Your team should read and discuss the list of required functionalities below and
create Asana tasks for the necessary features. You should discuss these and break
them down into necessary subtasks.

Required functionality
1. Create a Run class
The app should allow the user to track several different runs and calculate some
information for these. It will be necessary for the app to distinguish runs from one
another. You should create a Run class with several private attributes: the start
location (a LngLat object), the destination location (a LngLat object), an array of
locations (of LngLat objects) representing the path taken by the user, the date
(incl. time) the run was started, the date (and time) the run was completed, and
any other information you feel is necessary.
2. Location detection and tracking
When the user launches the New Run page, the app should locate the user and
display their position and location accuracy on an interactive map. This
information should be updated as the user’s location changes or increases in
accuracy.

Note:
● The builtin JavaScript geolocation API can be used to watch the user’s
location. Using the watchLocation method, this code will call a callback
function for every location change and give the new location as an
argument. This is the approach used in the ENG1003 sensor test app we
explored in prac classes.
3. Destination generation and display
There should be a button on the app’s New Run page which can be tapped to
generate a new destination (a random nearby location). This random location
should be based off the current position of the user (between 60m and 150m away
from it). This button should be initially disabled and should become enabled when
the user’s location accuracy first drops below 20 metres for the first time.

You should ensure that the logic for generating a random destination is
implemented as a function called ‘randomDestination’ which takes as a single
argument, a LngLat object, representing the current location, and returns a LngLat
object representing the new random location.

Function Name File Input Output
randomDestination newRunPage.js LngLat of current
location
LngLat of new
location

The destination should be displayed on the map and the app should display an
estimated distance from the user’s current location to the destination (assuming a
direct path from one to the other). This distance estimate should update as the
user’s position changes.
Note:
● Random values can be generated in JavaScript with the builtin
Math.random function, as we did in the Dice Rolling prac exercise.
● Modifying a longitude and latitude by a random amount up to ±0.001 will
result in a change of no more than 150m.
● You should check that your randomly generated location is not less that 60
metres from the user’s current location. If it is, you should silently select a
new destination, so the user doesn’t receive destinations too close to their
position.
4. Beginning a run
The New Run page should have a button to begin the run. When this button is
tapped, the user is expected to run to the destination. The app should set the start
location and time for the run and begin recording the route. You should store this
in a new instance of your Run class.

This “begin run” button should be disabled until the user has selected a destination.

As the user runs, the app should continue tracking and displaying their position on
the map and displaying the estimated distance to the destination. In addition to this,
the app should display the estimated distance from the starting location (assuming a
direct path from one to the other).
5. Completing a run
When the user is very close to their destination (for example, within 10 meters)
the app should end the run and record the completion time for the run.

You should add two methods to the Run class which calculate the total distance
travelled by the user and the duration (time taken). The app should display the
time taken for the run and distance travelled.
6. Persistent storage of Run instances
The New Run page should provide the user the ability to save the new run once
they have completed it (disabling the button before this). This “save” action should
store the new Run instance in local storage and then return the user to the Past
Runs List (index) page.

Note:
● Be sure that you store runs in such a way that you can retrieve all of your
runs from local storage later.
● You may choose to allow the user to store a given run with a
nickname/short description for easy identification later.
7. Showing a list of Runs
Once you have one or more Run instances stored in local storage, you should
modify the Past Runs List (index) page so that it displays a list of Runs that can be
viewed. This list should be generated from information in local storage and should
include the date/time when the run was recorded (and any other information you
would like to display). Clicking on an entry in the list should cause the app to
navigate to the View Run page and display that Run.
8. Viewing a Run
When the user views an existing run via the View Run page, the app should display
the run on an interactive map, including the start location, destination and
intermediate path.

This page should provide the user a method to delete that Run, which should
remove the Run from local storage and return the user to Runs List (index) page.

This page should display the distance of the run and the duration, along with the
average speed for this run.
9. Repeating a Run
The app should allow the user to try and improve their time for a given run. The
View Run page should have a “Reattempt” button that takes the user to the New
Run page but pre-sets the starting location and destination rather than allowing the
users to select these.

When the user reattempts the run, the app should prevent them from starting the
run until they are near the start location of that run. For this the new Run page
will need to respond differently for reattempted runs, i.e., track the user prior to
beginning the run.

The programming tasks together are worth 12% of your unit mark.

Your team can modify or extend your app as you like, provided it has the required
functionality. In particular, ensure you consider usability when designing the behaviour of
the app.
Technical documentation

Your team should produce two short pieces of technical documentation for your app:
● A basic Project Management Plan. This is internal documentation detailing:
○ Project aim and scope
○ Team members, and their responsibilities
○ How you are going to do the project, e.g., team meetings, minutes,
handling communication of changes to the code
○ Any other information you would want to give to a new team member
● A User Guide. This is external documentation detailing:
○ How to get started using the app, with screenshots
○ Any known bugs or limitations
● A Class Diagram.
○ The full set of classes used in the code(including all their attributes,
methods, and class name) (excluding API classes)
○ The relationship(s) between different classes
○ These should be prepared as a diagram on the computer e.g viso,
powerpoint, google drawings etc.

Your team will be assessed based on the quality of these documents. This will be worth 6%
of your final mark for the unit.
Presentation
Your team has now finished (or mostly finished) the prototype running app for the Osnean
Institute of Sport. Their representative, Tony Heelson, has organised time for each of the
prospective teams (yours and your competitors) to demonstrate their apps. Based on the
client’s satisfaction with the prototypes and presentations, they will decide which team will be
awarded the contract to produce the full app.

While you will be primarily presenting to the client (OIS), your team can expect both
representatives from the client as well as other hopeful software teams to be in the
audience. Ensure that your presentation explains the features of the app. It should explain
how the app works and describe any specialised hardware required. You should talk at a
high-level about architecture in order to explain how the app might be extended or what
additional features could conceivably be built on top of it, but you should be careful not to
include too much technical detail or jargon.

This presentation will be a formal client presentation delivered in front of your prac class. It
will be based on the app you produced for Assignment 2. As with any good presentation, it
should be prepared well in advance of the due date (including any visual aids) and it should
be well rehearsed as a team.
Format
Each student team will deliver a 15-minute oral presentation (in week 12 prac class)
describing and demonstrating their app and detailing any issues. Every member of the team
should present for 3-5 minutes.
● The target audience for this presentation is the client for the project
● This presentation will be delivered in a business setting and so all team members
should be dressed appropriately
● This presentation must discuss the design, structure and functionality of the
application

This presentation will be worth 6% of your final mark for the unit.
Testing the app
1. Save your assignment folder on your mobile device selecting \Transfer _les (MTP)
option" under "Use USB for".
2. Go to file:///sdcard/ using google browser (on your mobile phone, open google
browser and write file:///sdcard/ in the address bar),
3. Then select your folder and click on the index.html file
Resources
● MDL: Material Design Lite documentation
● Mozilla Developer Network: Using geolocation guide
● Mozilla Developer Network: Date documentation
● Mozilla Developer Network: random function
● Mapbox API: Map class
● Mapbox API: Marker class
● Mapbox API: other useful classes
Submission
Your team should submit their final version of the application online via Moodle; You must
submit the following:

● A zip file of your Assignment 2 folder, named based on your team (e.g.,
“Team014.zip”). This should contain your code and documents with the folder
structure below. This should be a ZIP file and not any other kind of compressed
folder (e.g. .rar, .7zip, .tar).

Please ensure that your Assignment 2 folder (and Bitbucket remote repository) use the
following structure:
assignment2
├── code
│ ├── css
│ │ └── runChallenge.css
│ ├── images
│ │ └── icon.png
│ ├── index.html
│ ├── js
│ │ ├── mainPage.js
│ │ ├── newRunPage.js
│ │ ├── shared.js
│ │ ├── utility.js
│ │ └── viewRunPage.js
│ ├── newRun.html
│ └── viewRun.html
└── docs
├── ProjectManagementPlan.pdf
├── UserGuide.pdf
└── ClassDiagram.pdf


The submission should be uploaded to Moodle by the team leader and must be finalised by
Friday Week 11, 11:55PM (Local Campus Time). Please note: Your entire team needs to
accept the assignment submission statement individually on Moodle.

You also need to individually complete the CATME peer assessment survey as described
below.

Your assignment will be assessed based on the contents of the assignment 2 folder you
submit via Moodle. You should ensure that the copy of the assignment submitted to
Moodle is the final version that exists in your repository. We will use the same phones as
your team phone when marking your assignment.

Your presentation will be during your practical classes in Week 12.
Marking criteria
Programming tasks
This assignment consists of several component assessment items with the following
associated marks (percentages of total marks for the unit):
● App code and functionality — 12% (group)
● Production of technical documentation — 6% (group)
● Presentation - individual component — 3% (individual)
● Presentation - Team component — 3% (group)
● Use of appropriate tools — (used to calculate individual contribution factor)

Assessment criteria:
● Required functionality and correct behaviour of the produced app
● Quality of app source code, including code documentation and overall structure
● Clarity and quality of individual oral presentations
● Structure, appropriateness, and level of team-client presentation
● Participation and appropriate use of tools for team software development, including
communication style
● Appropriateness of technical documentation, including structure, completeness and
communication quality

You will be marked as a group however your individual marks will be subject to peer review
moderation based on CATME feedback and scaling factors.

A detailed marking rubric will be available on the unit Moodle page.
CATME Peer Assessment
You are expected to work together as a team on this assignment and contribute roughly
equal amounts of work. Peer assessment will be conducted via the CATME online system.
You will receive email reminders at the appropriate time.

Not completing the CATME peer assessment component may result in a score of zero for
the assignment.


Do:
● Give your teammates accurate and honest feedback for improvement
● Leave a short comment at the end of the survey to justify your rating
● If there are issues/problems, raise them with your team early
● Contact your demonstrators if the problems cannot be solved amongst yourselves

Do NOT:
● Opt out of this process or give each person the same rating
● Make an agreement amongst your team to give the same range of mark
Contribution through use of collaborative tools
Each team member will be individually assessed on their use of three tools for
collaborative software development:

● Bitbucket (and GitKraken desktop client) for managing revisions of the app source,
and handling commits by multiple team members.
● Asana for team communication, project management and issue tracking.
● Google Drive for document authoring.

The history of your contribution over the entire period of the assignment, on Bitbucket,
Asana and Google Drive will be individually considered. For the use of each of these tools
you will be given a score depending on your observed level of contribution. Students with
less than the acceptable level of contribution for will incur a penalty to their assignment
mark:

Score Penalty
No contribution 10%
Some contribution 5%
Appropriate contribution 0%

Note: it is not enough to just use these tools for some dummy actions just prior to
submission—this will not be counted. It is expected that you will use these tools regularly
throughout the term of the assignment. You must give your demonstrator access to your
team Asana workspace and Google Drive folder for Assignment 2.
Assignment code interview
During your week 12 prac class your demonstrator will spend a few minutes interviewing
each team member to individually gauge the student's personal understanding of your
Assignment 2 code. The purpose of this is to ensure that each member of a team has
contributed to the assignment and understands the code submitted by the team in their
name.

You will be assigned a score based on your interview, and your code mark will be penalised
if you are unable to explain your team’s submission:
Category Description Penalty
No
understanding
The student has not prepared, cannot answer even the most basic
questions and likely has not even seen the code before.
100%
Trivial
understanding
The student may have seen the code before and can answer something
partially relevant or correct to a question but they clearly can’t engage in
a serious discussion of the code.
30%
Selective
understanding
The student gives answers that are partially correct or can answer
questions about one area correctly but another not at all. The student has
not prepared sufficiently.
20%
Good
understanding
The student is reasonably well prepared and can consistently provide
answers that are mostly correct, possibly with some prompting. The
student may lack confidence or speed in answering.
10%
Complete
understanding
The student has clearly prepared and understands the code. They can
answer questions correctly and concisely with little to no prompting.
0%


Presentation
Students are assessed on their individual presentation skills using the following criteria:
● Voice is of appropriate volume, speed and enthusiasm
● Language is appropriate for a formal context and doesn’t include unnecessary jargon
● Eye contact is consistent and covers most of the audience
● Body language complements the presentation
● Explanations are clear and visual aids used appropriately

Teams are assessed on the structure and management of the presentation using the
following criteria:
● Introduction clearly identifies the members of the team, what is to be spoken about,
and who is talking about what
● Conclusion clearly closes the presentation and refers to previously covered content
● Material included is relevant, justified and of high quality
● Speakers are given an equal share of time and are smoothly transitioned between
● The presentation adheres to the required time limit and the time spent on a section is
appropriate for the complexity of that section
● Attire is appropriate for a formal setting
● Appropriate use of visual aids
Final marks will be a combination of both the individual and team marks.
Other information
Where to get help
FAQs are at the end of this document and you can also ask questions about the assignment
on the General Discussion forum on the unit’s Moodle page. This is the preferred venue for
assignment clarification-type questions. You should check this forum (and the News and
Announcements forum) regularly, as the responses of the teaching staff are "official" and
can constitute amendments or additions to the assignment specification. Before asking for a
clarification, please check the FAQ and forum.
Plagiarism and collusion
Cheating and plagiarism are serious academic offenses at Monash University. Students
must not share their team’s work with any student outside of their team. Students should
consult the policies linked below for more information.
https://www.monash.edu/students/academic/policies/academic-integrity
http://eng.monash.edu.au/current-students/cheating-and-plagiarism.html
Students involved in collusion or plagiarism will be subject to disciplinary penalties, which
can include:
● The work not being assessed
● A zero grade for the unit
● Suspension from the University
● Exclusion from the University
Late submissions
We do not accept late submissions without special consideration. Such special consideration
applications should be made to the unit email address with a completed form and supporting
documentation within two business days of the assignment deadline.
http://www.monash.edu/exams/changes/special-consideration

Unavailable team members
If team members are missing on the day of the presentation, the remaining members should
proceed without them. Missing team members will receive a mark of zero unless they are
granted special consideration. Such special consideration applications should be made to
the unit email address with a completed form and supporting documentation within two
business days of the presentation date.
http://www.monash.edu/exams/changes/special-consideration

You must also inform your teammates if you will be absent on the day of the presentation.




Frequently Asked Questions

1. Will the assignment app work on iPhone?
Yes, this app should work fine on iPhone.
2. Where should I start for Assignment 2?
You should look into the Assignment 2 instruction under "Getting Started" subsection.
3. I have correctly setup the Mapbox API, my initMap function and there are no
errors, but still my map doesn't display. Why?
The map is being given a height of zero. You can specify a height for it in one of two
ways (in the .css file for the app):
#map {
height: 400px;
}
which makes the map 400 pixels high, or the more complicated expression
#map {
height: calc(100vh - 300px);
}

can be used to set the map height to be 100% of the view height minus 300 pixels. This
can be useful if you have other things on the page with fixed height and you want the
map to take up the rest of the available screen space.
4. Does the assignment need to be tested on the server and the team phone?
No, most of the assignment can be tested on Desktop Chrome. Only the GeoLocation
(GPS) API does not work on desktop Chrome and will require you to test it on the team
phone.
5. How can JavaScript on one page access and modify content in a div on another
HTML page?
You can't do this, i.e., the code for the Add Region page can't reference and populate
the regionsList div on the Main page. The browser only has the DOM instance for the
currently loaded page. The JavaScript on the page only has access to the DOM
instance for the current page.
In order to affect the content of another page, you need to have the current page save
information you want the second age to see to local storage, update the location to the
second page, and then have the code of the second page look at that information in
local storage to determine what it displays. This was demonstrated by the location
selection code (and subsequent title display on the View Region page) in the app
skeleton. This is exactly the Settings page for the Playground works.
6. Why are my initial GPS locations so inaccurate?
There is a setting on your phone under Settings -> Location. This should be set to "High
Accuracy". Sometimes it may default to "Battery saving".
It takes around one minute before you will start to receive really accurate location
information after you first initialise the GPS, since it takes time to get a full signal from a
couple of satellites (see our notes on this). You may find
navigator.geolocation.watchPosition() to work better than
navigator.geolocation.getPosition() as it constantly polls the GPS watching for location
changes.
You can also find the accuracy will get worse when you walk under buildings, or
between buildings with a narrow view of the sky.
WiFi connectivity shouldn't matter when using the app (other than you might not see
new map tiles). WiFi networks are only used for location information in the first minute
before the GPS really kicks in.
7. I have a lot of overlapping circles/markers/polygons displayed on the map.
Why? Or When I hit "Reset" only the last polygon/marker is removed. Why?
This is because you are creating an additional copy of a new
Marker/Polygon/Polyline/Circle class instance each time you want to remove it. Even
though you don't have a reference to the old ones, the Map does and still displays them.
You likely only have a reference to the latest copy.
If you are going to create a new annotation each time you want to redraw it, you need to
remove the old ones from the map. This can be done by setting the map property
to null via the addTo(null); method.
8. I tried to connect GitKraken from home, but it doesn't work. Why?
If you are accessing from home, you may need to VPN to Monash network first. Further
instructions are available here.
9. Can we add images to use in the app for buttons, pictures and custom markers?
No, sorry. However, you can upload images files via https://postimage.org/ and then use
the direct link to the image file that they provide in order to use the image from your app.
10. What constitute a good use of Tools (Asana, Bitbucket & Google Drive)?
The history of your contribution over the entire period of the assignment. It is
expected that you will use each of these tools regularly throughout the term of the
assignment. Note that it is not enough to just use these tools for some dummy actions
just prior to the submission deadline—this will not be counted. For the use of each of
these tools you will be given a score of “appropriate”, “some” or “none” depending on
your observed level of contribution. Students with less than the "appropriate" level of
contribution will incur a penalty to their assignment mark.
Some examples of contribution below:
Asana
Good: Regularly participated in creating and commenting on tasks in Asana over
assignment period. Worked with tasks effectively, e.g., adding descriptions, creating
subtasks, commenting on tasks, assigning tasks to team members/themselves,
completing tasks.
Bad: Created dummy tasks with meaningless titles or created and completed several
tasks just prior to submission.
Bitbucket
Good: Regularly committed and pushed meaningful changes (incl. log messages) to
team repository during the assignment period.
Bad: Committed and pushed a couple of trivial or unnecessary changes (such as
changing lowercase to uppercase or renaming files/functions) to remote repository,
or made some commits only immediately prior to submission.
Google Drive
Good: Regularly collaborated with team members to contribute to the authoring of
the PMP and User Guide drafts using Google Docs
Bad: Made only trivial contributions to documents, or only made changes to Google
Docs just prior to submission.
11. There are five different JavaScript files. Where should we put our code?
Code of any JavaScript file included via a script tag in an HTML file is available to other
code in the HTML file loaded after it. That is, code in a JavaScript file can use any
classes, function and global variables from itself or any JavaScript file loaded before it.
The utility.js file is included in each HTML page but shouldn't be edited. This contains
some shared code we have written: the displayMessage function that can be used to
show a toast (alert) message on the screen. Since it is included before the other
JavaScript files, you can call the displayMessage function from anywhere in your code.
The shared.js file is included in all HTML files too. It should contain any of your code
that you need to use from multiple places. This is likely to be the Run class, code to load
and save the Runs to/from localStorage, and any other helper functions you write. You
can use/call code in here from any of the three page specific JavaScript files.
There is a corresponding JavaScript file for each HTML file. Each of these should
contain code specific to that page, or code that needs to run when that page loads.
Since each of these files are included as the last JavaScript file, things defined in these
can't be used from shared.js or anywhere else.
12. I'm getting a weird error that mentions the snackbar. I'm pretty sure I didn't
change anything there, what gives?
You can fix this by ensuring the scripts are called on your html page and ensuring that if
you use displayMessage when the page loads, it uses what we describe in the question
below.
13. My displayMessage that runs when the page or js file is loaded doesn't work, and
I don't get any errors. How can I fix this?
This happens when the mdl js file is loaded but has not completed execution. You can
fix this by doing the following:
Assuming you have some functions or code that should run when the file is loaded.. i.e.
makeRunList();
displayMessage("Runs loaded",2000);
Put these into a function called initPage(), so you have
function initPage(){
makeRunList();
displayMessage("Runs loaded",2000);
}

and add this function to the same js file:
window.addEventListener("pageshow", function(event) {
initPage()
});
What this does is ensure that the code only fires when the page is fully loaded (i.e. the
mdl js has finished executing).
You will need to ensure that the mdl script tag in your html page has defer set, i.e.