This assignment is a JavaScript based assignment and this document outlines the requirements that must be met in order to obtain full marks.  This document is for both internal and external students, all work is done individually. Every person is required to use the JQuery JavaScript library to generate several tables and a graph based on JSON data and be able to demonstrate and explain their JavaScript code in person.

The Assignment

Your task is to plot the SAPOL Expiation data using the pre-configured web services and one of several options available for consuming the Bureau data!  The options are:

1. JQuery (using the ajax request)

2. D3 v5.9.x – newer than used in the past practicals which will also require some research

Your task is to consume Ajax Data and present them on the /Home/Expiations page as per the requirements below.

Requirements

There are several tasks you are required to complete as described below.  In addition, there are some restrictions on implementation:

· Data from the JSON must not be included in class names.  

· No id’s can be created other than those provided.  

· Strings used to create elements must not include class names or other html attributes.  

We want good coding practices here!

Task 1.  Expiation Code Data [30%]

1. The first thing we need is a table of the data from the  ExpiationsWebAPI Controllerto be displayed in our Expiations page already created for you.  This table should list the

· The Year (as a single colum table row)

· The various Expiation categories for that year

· The ticketCount for each category for that year

 

2. When the mouse cursor is over a row, the row should automatically highlight (and remain readable).  You can do this using the pre-existing bootstrap classes if the colours are suitable or make your own CSS selectors using an external style sheet linked at the top of the page.  If in doubt, look up the bootstrap table information.  The row should indicate that it can be clicked to view additional information:

 

3. Clicking on a row should highlight the row permanently until another row is clicked.  The year headings should not be clickable or become hilighted.

 

4. This table must be created inside the element with id="table" using an ajax-webservice data source with a timeout function. This must be done using the best JQuery approaches, namely appendTo().  There must be NO hard coded table elements or any other elements added to the page.  All elements in this assignment must be added dynamically using JQuery.

 

5. If the Ajax Fails, the entire table and graph div should be replaced with an appropriate error message (e.g., “Failed to load Expiation Data”).  Feel free to include an image of your choice to represent no data. No table or graph elements should exist if the request fails other than the two div’s provided.

Task 2.  Expiations Graph Monthly Breakdown [30%]

The second thing we need is a bar/column graph of the data depicting the selected expiation category and year from the table.  Clicking on a table rows should bring generate the graph alongside the table.  The graph must be generated using either JQuery or D3 v5.9.x.  No other chart/graph library or framework can be used.

1. The graph will be generated using data derived from the selected row of the table.  This graph can be generated from div elements (or any other suitable elements like svg if using D3 v5.9.x, NOT table elements).  To do this, you will need to research topics such as how to use a “for-each” loop and how to create html elements or append html using your chosen JavaScript library.  

· It is suggested you start by designing your graph statically using plain HTML and custom CSS classes so that you can determine the html design needed to implement the graph.

· Once your “static” graph is in order, translate this to your Ajax JQuery.

· Use console.log(“your text” + javaScriptVariale); to help you debug as you write the code.  If you are having troubles getting the web services working, then use the console of the browser (F12 in IE) and the network traffic in the browser to see if data is being sent and received.  

 

2. The bar/column Graph should have the year and selected category clearly indicated at the top of the graph using a suitable element (h4 in the example).  The y axis should have a Month label and the month names located left off each bar (or underneath if a column graph).  Ticket counts and should be clearly displayed within each bar.  Note that numbers should be right-aligned to improve readability.  

 

3. The bars will need to be scaled to consume the maximum available graphing space (ie use % not px if using div elements).  This will be tricky because the ticket count of the various months may differ dramatically.   If the Data is not available, then the bars should not be created/appended to the graph.

 

4. The colour of the bars should look attractive and professional – black and white is not sufficient.  The colours you choose should look professional.    

 

5. The bars must be animated.  When you first select an expiation, the graph title should appear and the bars should grow from 0% to their actual size (as determined by the expiation count).

 

6. When the mouse is hovered over a month on the graph, it should be highlighted.  When it highlights, a tool-tip should clearly indicate how many tickets were issued for that month and year, as well as indicating that the bar can be clicked to view a detailed breakdown for that year: “Click to view monthly detail for xx year”

 

7. The Graph requires a title and x-axis and y-axis lables.  These can be rotated or placed at the top left and bottom right of the graph as appropriate to make it look professional

 

A basic example of the proposed graph is provided below.  Your graph will need to look professional suitable for publishing online.  The same graph is shown twice to highlight that the bars grow to their appropriate width:

 

 

 

 

 

Task 3.  Expiation Code Breakdown [30%]

Clicking on a month bar in the expiation graph will cause generate a details table below the graph that shows the different offence codes, the offence code description, avg speed of vehicles, avg fine paid and the number of tickets issued for that particular speeding offence.  The table will need to have an appropriate title that reflects the category of speeding, the month and the year of the chosen bar from the graph.  Average values will need to be rounded to 2 decimal places and all numbers will need to be right aligned for readability:

 

 

The Web Application

A web application containing the necessary database and Web API web services has been created for you.  This can be downloaded from the assessments tab on the course website.  Your task is to complete the Views/Home/Expiations with the necessary layout, graphs and JQuery or D3v5.9.x/JavaScript code.  

If you wish to use D3 then you will need to link to the v5.9.x library.  This is included in the project but not on the master _Layout page.

The Web Services

Once you have your graph structure configured and made your decision on the JavaScript library to use (JQuery vs D3v5.9.x), it is suggested you get started creating an Ajax call to the ExpiationsWebAPIController web service and get the data to download to the page.  The relative URL for the web service is "/api/ExpiationsWebAPI".  So if you run the application in VS2017 and your root URL shows up as: http://localhost:55968/ then

http://localhost:55968/api/ExpiationsWebAPI will return the list of years, speeding categories and ticketCounts as Ajax Json data.  This may open up in Visual studio, in which case you can use Ctrl + K + D to auto format it into traditional JSON style:

[{"category":1,"expiationCategory":"1-9km/h","year":2016,"ticketCount":46128},{"category":2,"expiationCategory":"10-19km/h","year":2016,"ticketCount":64996},{"category":3,"expiationCategory":"20-29km/h","year":2016,"ticketCount":5987},{"category":4,"expiationCategory":"30-44km/h","year":2016,"ticketCount":1640},{"category":5,"expiationCategory":"45km/h or more","year":2016,"ticketCount":446},{"category":1,"expiationCategory":"1-9km/h","year":2017,"ticketCount":81033},{"category":2,"expiationCategory":"10-19km/h","year":2017,"ticketCount":120326},{"category":3,"expiationCategory":"20-29km/h","year":2017,"ticketCount":11260},{"category":4,"expiationCategory":"30-44km/h","year":2017,"ticketCount":2859},{"category":5,"expiationCategory":"45km/h or more","year":2017... }]

The next step would be to work out how to read and loop through the data. In the JsonData folder are various json files showing the data correctly formatted so that you can see the arrays and object through their indentation. Use these files to help you write your JQuery/D3v5.9.x code. You may even want to write your Ajax request to use these files to simplify testing. If you do this, remember to swap it back to the Ajax JSON web API requests when finished.

 Once this is working, start creating html elements and assigning them data before appending them to the page.

Once you have your expiation categories working, clicking on a code should navigate you to the next web service controller used to generate the monthly graph: GetExpiationsWebAPI(int category, int year) using the URL: /api/ExpiationsWebAPI?code=xx&year=yyyy

Clicking on a bar in the graph should trigger the next webAPI function for the details table: GetExpiationsWebAPI(int category, int year, int monthNo) using the URL: /api/ExpiationsWebAPI?code=a001&year=2018&monthNo=1 as an example.

Examples of the JSON returned can be found in the ExampleJson folder.  1_BuildTable.json provides an example of the initial table data.  2_BuildGraph.json provides an example of the JSON returned for the first table entry. Lastly, 3_BuildDetailTable provides example data of the first month selected from the above generated graph.

JavaScript (JQuery or D3)

The assignment is done individually and each person must write their own JavaScript code which includes their Ajax requests to perform the above tasks. As mentioned you can use JQuery OR D3v5.9.x to achieve the various tasks. Other versions of D3 (such as v3 or v4) will not receive any marks.

CSS

The style of the bars and layout of the axis can be done using embedded style elements for testing at the top of the page as necessary but then move these to an external style sheet. The exact spacing of the bars is not important but the graph must look professional: clean, be neat and readable. The statistical information and counts in the bars should be spaced away from the border so as to be easily readable. The codes, years and monthly markers of the bars should be adequately spaced from the bars so as to not overflow on to the chart. The number of style classes should be kept to a minimum unless required as part of visual feedback during mouse hover or for animations. The use of expiation data in Class Names and the use of ID’s will incur penalties.

Marking

Marking will be conducted in class during week 13. You will need to be able to demonstrate your work and answer any questions to obtain a passing grade. A failure to explain your code will result in reduced or no marks.

Marks will be allocated in the following areas:

Annual Expiation Category Table [30%]

This includes:

· Correct table structure (thead, tbody, th, colspan for year rows)

· Presentation and correct use of bootstrap classes.

· Quality of JQuery/D3v5.9.x code used to generate the table.

· Code to highlight selected data

· Timeout and error functions

Monthly Expiation Category Data Graph [30%]

· Ajax call to the WebAPI to pull the correct data

· Creation of html elements using JQuery/D3v5.9.x, including incorporating data and css classes into the new html elements

· Presentation and use of bootstrap classes where appropriate

· Use of JQuery functions over lengthy strings and concatenation

· Appending the data to the existing data div.

· Code to highlight bar and month of graph

· Quality of graph layout and readability.

· Colourisation of data

· Animation of bars

Expiation Code Detail Table [30%]

· Ajax call to the WebAPI to pull the correct data

· Creation of html elements using JQuery/D3v5.9.x, including incorporating data and css classes into the new html elements

· Use of bootstrap classes where appropriate

· Use of JQuery functions over lengthy strings and concatenation

· Appending the data to the existing data div.

· Code to highlight bar and month in graph

· Quality of graph layout and readability.

Code Quality [10%]

· HTML Validation – is your generated HTML valid?

· Optimisation of JQuery and data being consumed

· Strategic use of HTML structure, class names, data attributes, index information and foreach loops.

· Reuse of attributes.

 

 

Due Date

You will need to have your site completed for presentation which will take place in Week 13 during your practical time. You will need to upload a copy of your website by Tuesday 9am which will be used for further analysis of the individual assessment components. You MUST present your work in class of Week 13 to obtain a passing grade.