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 instanc
e 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.
