Ajax and jQuery - WheatonCS/Lexos GitHub Wiki
This wiki page is a guide for using Ajax and jQuery to pass information from frontend to the backend.
jQuery is a relatively lightweight JavaScript library that allows for a simplified way to interact with the Document Object Model or DOM for short. jQuery allows for a much simpler way to refer to the document when attempting to get data from an HTML page. jQuery functions require three basic parts, the $ flag to access the document, the name of a selector in quotes inside parentheses after the $, and the action taken on the selector. A comprehensive list of valid selectors can be found here. The basic setup looks like this
$(#selector).hide()
If the selector section is left blank, jQuery will use default to the document as a whole. For example,
$.ready()
will perform an action when the document itself is readied.
Ajax is a set of web technologies that allow asynchronously passing data between the front end JavaScript and, in the case of Lexos, the backend Python. The jQuery library comes with a full set of Ajax functions that are tailored to work with jQuery. You can find a list of the jQuery Ajax functions here. When working with Lexos, an Ajax request will need to take a few basic arguments, with room for more as the request demands. A comprehensive list of the potential arguments can be found here.
The basic arguments are type, url, contentType and data. Type will take one of three options, 'POST', 'GET' and 'PUT'. The default if no type is specified is 'GET', so be sure to specify if you this is not the desired action. Url will take the url of the page that the request is being sent to, for 'GET' it is where information is received from, and for 'PUT' and 'POST' it is where the data is being sent to. ContentType will take a string containing the type of content that is being sent in the Ajax request. Data will take the data that is being sent in the Ajax request.
For illustration here are examples of two Ajax requests from the Lexos production as of writing this wiki. The first example is for sending form data from the cut operation to the server. For readability, the Ajax call can be spaced out at the comma separations
$.ajax({ type: 'POST', url: 'cut/execute', processData: false, contentType: false, data: form_data })
This example is of sending a string of words for processing to the server using Ajax
$.ajax({ type: 'POST', url: 'bubbleviz/get-word-counts', contentType: 'application/JSON', data: JSON.stringify({maximum_top_words: $('#term-count-input').val()}) })
This example shows the way that strings have to be handled when passing them using Ajax. The Ajax data argument can only take one input, so when attempting to pass multiple datum, the JSON.stringify() function must be called on the dataset to convert the dataset into a single string that will then be parsed on the server side.
As of the writing of this wiki, the Lexos production has two Ajax specific functions. They are the send_ajax_request() and send_ajax_form_request() functions in the utility.js file. For more specific needs, individual Ajax requests can be written manually where they are needed, but in general you should try to use these functions where you can. For the pre and post conditions and the arguments of these functions, see their declarations in utility.js.