JavaScript Documentation

Anthony Armatas edited this page Mar 10, 2017 · 16 revisions

Javascript & Front End Documentation

High level overview of the main Javascript files:

  • index.js
  • The main Javascript file for the application, contains code that doesn't fit within the other .js files. Mainly the initialization code for the application and containers, along with multiple button handlers which serve as the logic portion between the UI and the API calls. Also contains the code for populating UI elements from the data returned from API calls
  • api.js
  • Handles sending and receiving data from the Flask backend server.
  • Contains multiple functions which take data for Ajax API calls to the endpoint. Each function that is not a log in takes the users authorization token and then the data relating to the functionality of the endpoint.
  • transitions.js
  • Handles the multitude of transitions needed by the application. Also contains the jump list for keeping track of transition flows. Uses JQuery toggle functions to give the application a nice animating appearance.
  • graph_rendering.js
  • Contains all of the code that generates the various graph representations and their selection overlays. The main build function takes two enums which specify the context that the graph is being created, and the type of graph to create. The build function also takes the specific JQuery container which the build function will be drawing the graphs into.

Low level overview of each function in the main Javascript files:

index.js

test()

  • Passed In
    • Null
  • Methods' Function
    • Gets the next test from the test set by passing in the users UUID to an api function.
  • Returns
    • Null

refresh_admin_page_lists()

  • Passed In
    • Null
  • Methods' Function
    • Refresh the admin page, clear all the selections (The template list and the Test set list).
  • Returns
    • Null

Handlers take a buttons event and tie them to middle or api code

admin_login_handler()

  • Passed In
    • Null
  • Methods' Function
    • When the admin clicks the [Login] button on the [admin sign in page] this function Get the creds from the input, and pass them to the api. API call to the admin_login endpoint.
    • The admin page will then slide up and allow access to all of the admin functions.
  • Returns
    • Null

view_template_handler()

  • Passed In
    • Null
  • Methods' Function
    • The function will populate the slide using populate_view_template_page() and will then show the slide/hide it when toggle_view_template(); is called.
  • Returns
    • Null

new_template_handler()

  • Passed In
    • Null
  • Methods' Function
    • Will open or close the new template page by calling toggle_new_template();.
  • Returns
    • Null

delete_template_handler()

  • Passed In
    • Null
  • Methods' Function
    • The method deletes the selected template by calling delete_template(credentials.auth_token, selected_template).done(function(value) and then calls refresh_admin_page_lists() from within, to show the changes after the deletion has taken place.
  • Returns
    • Null

view_test_set_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method gets the selected test set details by using the get_test_set_details() method. It then populates the page with the populate_view_test_page() method passing in the values get_test_set_details() provided. The method ends by calling the toggle_view_test_set() which should then show the newly populated page.
  • Returns
    • Null

new_test_set_handler()

  • Passed In
    • Null
  • Methods' Function
    • This function gets the new test set page ready. It calls the api function get_template_ids and passes its value to populate_admin_page_new_test_set_templates. After the selection is populated with templates the page is opened by calling toggle_new_test_set();.
  • Returns
    • Null

download(text, name, type)

  • Passed In
    • String:text, String:name, int(usually 0,1,or 2):type
  • Methods' Function
    • Creates a variable "a" which is set to the element ID download-button. Then opens a new file, which passes in the text and specifies the passed in type as the predefined type (text/plain). a's href is set to the created opject which passes in the newly created file, and then a downloads the CSV document with the passed in name.
  • Returns
    • Null

export_test_set_handler()

  • Passed In
    • Null
  • Methods' Function
    • When the user clicks the [Export] button on the [admin home page] this function is called. it calls the api function export_csv and sets that newly created csv variable to the value passed in by the api call. It then calls the previously created download function download().
  • Returns
    • Null

delete_test_set_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method simply calls the api method delete_test_set() and then calls refresh_admin_page_lists(); to update the main admin page to represent the changes.
  • Returns
    • Null

open_test_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method simply calls the api method open_test() and then calls refresh_admin_page_lists(); to update the main admin page to represent the changes.
  • Returns
    • Null

close_test_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method simply calls the api method close_test() and then calls refresh_admin_page_lists(); to update the main admin page to represent the changes.
  • Returns
    • Null

begin_training_handler()

  • Passed In
    • Null
  • Methods' Function
    • Calls toggle_training_intro_view(); to show the intro to the training page.
  • Returns
    • Null

training_fwd_movement()

  • Passed In
    • Null
  • Methods' Function
    • Calls transfer_through_training(); to move through the training pages.
  • Returns
    • Null

noSpaces(idName)

  • Passed In
    • idName:String
  • Methods' Function
    • This methods purpose is to walk through the added string name and replace every space with a hyphin. It first checks to see if nothing was passed in, if so it does nothing. If there is a string, it sets its value to the var str, and that string calls .replace to replace the ever space with a '-'. The idName.val() passes in the new spaceless value.
  • Returns
    • Null

populate_view_template_page(template_details)

  • Passed In
    • template_details: Total data points, and the graph type
  • Methods' Function
    • The methods purpose is to populate the view template page with whatever tempalte was selected. The first thing this method does is empty out what might have been in the populate template page before. It then sets the total datapoints and graph type to variables. It then appends a paragraph tag to the view-template-center div, followed by another paragraph but this time concatinated by the actual data values of the total data points and graph type. After that, it then creates a third div, followed by a build call to creat a graph the has both of the properties shown above.
  • Returns
    • Null

populate_view_test_page(test_details)

  • Passed In
    • template_details: Total data points, and the graph type
  • Methods' Function *Takes the response from the [get_test_set_statuses] API call and parses it into the trial-view-admin-panel-id-list, which is in need of a rename
  • Returns
    • Null

populate_admin_page_active_tests(test_statuses)

  • Passed In
    • test_statuses:A container of data.
  • Methods' Function
    • Takes the response from the [get_template_ids] API call and parses it into the test-status-list
  • Returns
    • Null

populate_admin_page_test_templates(test_templates)

  • Passed In
    • test_templates:Container of data which lists the current test templates
  • Methods' Function
    • This method empties the test tamplates list that is currently showing, and goes through each template passed in and creates a new test template with its name and type for each template availible.
  • Returns
    • Null

set_template_selection(template_name)

  • Passed In
    • template_name: String value of the passed in template name.
  • Methods' Function
    • This method takes in the passed in value and adds it to template list shown to the admin.
  • Returns
    • Null

set_trial_selection(trial_name)

  • Passed In
    • trial_name: String value of the passed in trial name.
  • Methods' Function
    • This method takes in the passed in value and adds it to test set list shown to the admin
  • Returns
    • Null

populate_admin_page_new_test_set_templates(test_templates)

  • Passed In
    • test_templates:Container of data which lists the current test templates
  • Methods' Function
    • Removes all the old data from the selection box in the new test set page and fills it with all of the current test templates.
  • Returns
    • Null

timeChangeSecToMin()

  • Passed In
    • Null
  • Methods' Function
    • Takes the time in seconds and sets the div time_in_min to that time in minutes.
  • Returns
    • Null

timeAllotedChangeSecToMin()

  • Passed In
    • Null
  • Methods' Function
    • Takes the time in seconds and sets the div alloted_time_in_min to that time in minutes.
  • Returns
    • Null

setMinTime()

  • Passed In
    • Null
  • Methods' Function
    • Blocks the admin from making the close time of a test set prior to the current date in test_set_close_time.
  • Returns
    • Null

addToSelectedTemplates()

  • Passed In
    • Null
  • Methods' Function
    • Method for adding the selected templates from one select box to another, in New Test Set.
  • Returns
    • Null

addALLToSelectedTemplates()

  • Passed In
    • Null
  • Methods' Function
    • Method for adding ALL of the select templates from one select box to another, in New Test Set.
  • Returns
    • Null

removeFromSelectedTemplates()

  • Passed In
    • Null
  • Methods' Function
    • Method for removing the selected templates from one select box, in New Test Set.
  • Returns
    • Null

addALLToSelectedTemplates()

  • Passed In
    • Null
  • Methods' Function
    • Method for removing ALL of the select templates from one select box, in New Test Set.
  • Returns
    • Null

create_new_template_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method takes in all of the values from the new template page and calls the api function new_test_template() to actually create it, and then calls toggle_new_template() to bring the user back to the main screen.
  • Returns
    • Null

create_new_test_set_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method takes in all of the values from the new test setpage and calls the api function new_test_set() to actually create it, and then warns the user to give the Software a second to update and then calls toggle_new_test_set() to bring the user back to the main screen.
  • Returns
    • Null

graph_type_radio_handler(value, data_points)

  • Passed In
    • value: int(the type of graph), data_points: int(amount of dpts)
  • Methods' Function
    • This method calls a build function to show whichever type the radio button is called.
  • Returns
    • Null

data_point_change_handler(value, data_points)

  • Passed In
    • int(the type of graph), data_points: int(amount of dpts)
  • Methods' Function
    • This method calls a build function to show whichever type the radio button has changed to.
  • Returns
    • Null

testing_page_timeout()

  • Passed In
    • Null
  • Methods' Function
    • This method checks to see if the testing page has timed out.
  • Returns
    • Null

training_page_timeout()

  • Passed In
    • Null
  • Methods' Function
    • This method checks to see if the training page has timed out.
  • Returns
    • Null

wait_page_timeout()

  • Passed In
    • Null
  • Methods' Function
    • This method checks to see if the waiting page has timed out.
  • Returns
    • Null

start_testing_handler()

  • Passed In
    • Null
  • Methods' Function
    • This method starts the actual testing for the site. It calls the api function get_next_test() while passing in the uuid. It generates the parent class and child classes from the test returned from the previous api call. It alos initilizes the timer for the test.
  • Returns
    • Null

continue_to_wait_page_handler()

  • Passed In
    • Null
  • Methods' Function
    • This function pushes the users test data to the DB and moves the user to the waiting page.
  • Returns
    • Null

continue_testing_handler()

  • Passed In
    • Null
  • Methods' Function
    • This function gets the user to the next test page from the training page.
  • Returns
    • Null

api.js

function admin_login(email, password)

  • SENDS : Username, Password
  • Methods' Function
    • This method takes in the given email and password and if it succeeds it returns a success value. If it fails it alarts the adminof an api failure.
  • RECEIVES : Unique login token

trial_login(login_uuid)

  • API call to : "/auth/trial_login"
  • Methods' Function
    • This method takes in the users UUID given to them by the admin. It it will return succuss or failure to the handler depending on whether the UUID is in database.
  • RECEIVES : Success or fail

get_test_set_statuses(auth_token, filter)

  • SENDS : Login Token, Optional filter
  • Methods' Function
    • This populates the test set lists but only with those of the correct filters.
  • RECEIVES : JSON list of test set id and their statuses {0, ANY} {1, RUNNING} {2, COMPLETE} {3, PARKED}

get_template_ids(auth_token, filter)

  • SENDS : Login Token, filter
  • Methods' Function
    • This populates the template lists but only with those of the correct filters
  • RECEIVES : JSON list template-ids combined with their test type

submit_user_trial_results(login_uuid, selected_points, selected_classes, result, time)

  • SENDS : The results of the trial
  • Methods' Function
    • This method will submit the users trail results to the database, and will return either success or failure to the system.
  • RECEIVES : Success or fail

export_csv(auth_token, trial_id)

  • SENDS : Auth token, the trial to export
  • Methods' Function
    • This method gets the CSV information from the database and returns the CSV info in text form.
  • RECEIVES : A CSV file in text form

delete_test_set(auth_token, trial_id)

  • SENDS : The selected trial ID
  • Methods' Function
    • This method will attempt to delete the passed in test set from the Database, and will return success or a failure.
  • RECEIVES : Success or fail

delete_template

  • SENDS : The selected template ID
  • Methods' Function
    • This method will attempt to delete the passed in test set from the Database, and will return success or a failure.
  • RECEIVES : Success or fail

new_test_set(auth_token, test_set_id, alloted_test_time, template_list, wait_time, close_time, uuid_count)

  • SENDS : A JSON object specifying the test set variables
  • Methods' Function
    • This function will attempt to create a new test set in the database, and will return success or fail values.
  • RECEIVES : Success or fail

get_next_test(login_uuid)

  • SENDS : Users uuid
  • Methods' Function
    • It checks the UUID of the user, and finders the next test in the set,
  • RECEIVES : // RECEIVES : If there is another test in the queue it receives a JSON object like this
  •             JSON = {
    
  •                 "class1_example" : [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    
  •                 "class2_example" : [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    
  •                 "class1_data"    : [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]],
    
  •                 "class1_data"    : [[1, 2, 3, 4, 5, 6, 7, 8, 9, 10], [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]],
    
  •                 "time": "60",
    
  •             };
    
  •             Otherwise, it will get a JSON object specifying the users results
    
  •             JSON = {
    
  •                 "total_time": "1234",
    
  •             };
    

open_test(auth_token, test_set_id)

  • SENDS : Auth creds and the id of the test to open
  • Methods' Function
    • Opens the test for the user to take.
  • RECEIVES : Success or fail

close_test(auth_token, test_set_id)

  • SENDS : Auth creds and the id of the test to close
  • Methods' Function
    • Closes the test after the user completes it.
  • RECEIVES : Success or fail

get_template_details(auth_token, template_id)

  • SENDS : Auth token, the template id
  • Methods' Function
    • Takes the template information and gathers the info from the database.
  • RECEIVES : JSON object with total_data_points, graph_type

new_test_template(auth_token, template_id, graph_type, total_data_points)

  • SENDS : A JSON object specifying the template variables

  •             JSON = {
    
  •                      "login_token"  : credentials.auth_token,
    
  •                      "test_set_id"  : "trial-1",
    
  •                      "template_ids" : ["template-1" , "template-1", "template-2"],
    
  •                      "wait_time"    : "60",
    
  •                      "close_time"   : "timestamp of some sort",
    
  •                      "uuid_count"   : 30
    
  •             };
    
  • Methods' Function

    • Sends the values passed in to the database to create a new test template.
  • RECEIVES : Success or fail

new_admin(auth_token, email, password)

  • SENDS : Passes in the auth_token and the entered string email and password
  • Methods' Function
    • Sends the email and password to the databased and returns success or failure depening on whether or not the DB accepts the information.
  • RECEIVES : Success or fail

transitions.js

A lot of the functions in this js file use these defined var's: var screen_enum = { HOME: 1, ADMIN_HOME:2, TEST_NEW:3, TEST_VIEW:4, TEMPLATE_NEW:5, TEMPLATE_VIEW:6, TRAINING_INFO:7, TRAINING_HOW_WORK:8, TRAINING_PRAC:9, TRAINING_RESULTS:10, TESTING_START:11, TESTING_TEST:12, TESTING_WAIT:13, TESTING_FINISH:14, NEW_ADMIN:15 };

var screen = screen_enum.HOME;

transfer_back()

  • Passed In
    • Null
  • Methods' Function
    • This function checks the current state of screen, and changes it to go to its previous page.
  • Returns
    • Null

transfer_through_training()

  • Passed In
    • Null
  • Methods' Function
    • This function checks the current state of the training screen, and changes it to go to its previous page.
  • Returns
    • Null

show_trial_login()

  • Passed In Null *
  • Methods' Function
    • Hides the div right-hand-container, and shows the div trial-login-div.
  • Returns
    • Null

show_training_info

  • Passed In *
  • Methods' Function
    • Hides the div right-hand-container, and shows the div trial-login-div.
  • Returns *

  • Passed In
    • Null
  • Methods' Function
    • Hides the div right-hand-container, and shows the div training-info-div.
  • Returns
    • Null

  • Passed In *
  • Methods' Function
    • Hides the div right-hand-container, and shows the div about-div.
  • Returns *

show_admin_login()

  • Passed In
    • Null
  • Methods' Function
    • Hides the div right-hand-container, and shows the div admin-login-div.
  • Returns
    • Null

toggle_view_test_set()

  • Passed In
    • Null
  • Methods' Function
    • Toggle functions for opening and closing the test set page.
  • Returns
    • Null

toggle_new_test_set()

  • Passed In
    • Null
  • Methods' Function
    • Open and close the new test set page
  • Returns
    • Null

toggle_new_template()

  • Passed In
    • Null
  • Methods' Function
    • Open and close the new template page
  • Returns
    • Null

toggle_new_admin()

  • Passed In
    • Null
  • Methods' Function
    • Open and close the new admin page
  • Returns
    • Null

toggle_view_template()

  • Passed In
    • Null
  • Methods' Function
    • Open and close the new view template page
  • Returns
    • Null

toggle_admin_panel()

  • Passed In
    • Null
  • Methods' Function
    • Open and close the main admin page
  • Returns
    • Null

toggle_start_testing()

  • Passed In
    • Null
  • Methods' Function
    • Open and close the start test page
  • Returns
    • Null

toggle_test_from_start()

  • Passed In
    • Null
  • Methods' Function
    • Starts the test page from the begining of the test test and not the a normal test page.
  • Returns
    • Null

toggle_wait_from_test()

  • Passed In
    • Null
  • Methods' Function
    • opens and closes the waiting page.
  • Returns
    • Null

toggle_test_from_wait()

  • Passed In
    • Null
  • Methods' Function
    • Opens the next test page from the wait page.
  • Returns
    • Null

  • Passed In
    • Null
  • Methods' Function *
  • Returns
    • Null

toggle_finish_from_wait()

  • Passed In
    • Null
  • Methods' Function
    • Opens the thank you page from the test page.
  • Returns
    • Null

toggle_finish_from_test_start()

  • Passed In
    • Null
  • Methods' Function
    • Opens the thank you page from the start page.
  • Returns
    • Null

stop_testing()

  • Passed In
    • Null
  • Methods' Function
    • Closes the test page and brings forward the main page.
  • Returns
    • Null

toggle_home_from_training()

  • Passed In
    • Null
  • Methods' Function
    • Brings the user back to the main screen from the training info
  • Returns
    • Null

toggle_intro_from_selection()

  • Passed In
    • Null
  • Methods' Function
    • Brings the user back from the selection training to the training info
  • Returns
    • Null

toggle_selection_from_practice()

  • Passed In
    • Null
  • Methods' Function
    • Brings the user back from the practice training to the selection training
  • Returns
    • Null

toggle_practice_from_results()

  • Passed In
    • Null
  • Methods' Function
    • Brings the user back from the practice training to the selection training
  • Returns
    • Null

toggle_training_intro_view()

  • Passed In
    • Null
  • Methods' Function
    • This is the function which brings the training page to the front
  • Returns
    • Null

toggle_training_selection_view()

  • Passed In
    • Null
  • Methods' Function
    • This is the function which brings the specifics of taking the test page to the front
  • Returns
    • Null

toggle_training_practice_view

  • Passed In
    • Null
  • Methods' Function
    • This is the function which brings the practice page to the front
  • Returns
    • Null

toggle_training_results_view()

  • Passed In
    • Null
  • Methods' Function
    • This is the function which brings the training results page to the front
  • Returns
    • Null

toggle_back_to_home()

  • Passed In
    • Null
  • Methods' Function
    • This function brings the user from the training results page to the main page.
  • Returns
    • Null

graph_rendering.js

These functions go off of the assumtion that the variables: graph_dimensions = {width:175, height:175} let training_graph_arr = [] let testing_graph_arr = [] are initiated

testing_graph_click(graph_index, data_index)

  • Passed In
    • The graph which is being clicked and the section of the graph that was clicked.
  • Methods' Function
    • This method handels the selection of the sections of the graph of real tests.
  • Returns
    • Null

training_graph_click(graph_index, data_index)

  • Passed In
    • The graph which is being clicked and the section of the graph that was clicked.
  • Methods' Function
    • This method handels the selection of the sections of the graph of practice tests.
  • Returns
    • Null

build(container, context, type, data)

  • Passed In
    • container: the div where the test will be created, context: the situation determining the functionality of the individual graphs, type: the type of graph to be built, data: the amount of datapoints each graph will contain.
  • Methods' Function
    • This function builds a test containing multiple graphs which use the passed in data to define each of the graphs.
  • Returns
    • Null

build_linear(context, data_array)

  • Passed In
    • context: the situation determining the functionality of the individual graphs, data_array: the array of data which will be used to build the graphs.
  • Methods' Function
    • This is a method called in build which will actually build the individual linear graphs.
  • Returns
    • Returns the graph data container which the click methods interact with

build_star(context, data_array)

  • Passed In
    • context: the situation determining the functionality of the individual graphs, data_array: the array of data which will be used to build the graphs.
  • Methods' Function
    • This is a method called in build which will actually build the individual star graphs.
  • Returns
    • Returns the graph data container which the click methods interact with

edgeOfView(rect, deg)

  • Passed In
    • rect: An object which will determine the demensions of the container of each graph, deg: the theta value for operations in the method.
  • Methods' Function
    • This method creates the container in which each graph is held.
  • Returns
    • Math.floor(Math.random() * (max - min + 1)) + min;

rand()

  • Passed In
    • Null
  • Methods' Function
    • Generates a random number.
  • Returns
    • Math.floor(Math.random() * (max - min + 1)) + min;

generate_class_data(data_point_count)

  • Passed In
    • data_point_count: the amount of datapoints of the graph
  • Methods' Function
    • This generates all of the data in both the class graphs and the graphs derived from those classes for the practice test.
  • Returns
    • ret_data

generate_class_data_viewTemplate_ed(data_point_count)

  • Passed In
    • data_point_count: the amount of datapoints of the graph
  • Methods' Function
    • This method generates the graphs for the view template page which will use the values of the template the admin is viewing.
  • Returns
    • ret_data

generate_parent_data(data_point_count)

  • Passed In
    • data_point_count: the amount of datapoints of the graph
  • Methods' Function
    • This is used to create the graphs for when the admin changes the radio button on the create test template page.
  • Returns
    • ret_data
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.