From ff7881662ca8214cdaaf24f972cd781268205f70 Mon Sep 17 00:00:00 2001 From: Stephan Porada Date: Wed, 9 Sep 2020 09:31:20 +0200 Subject: [PATCH] Documentation for Client.js --- .../modules/corpus_analysis/client/Client.js | 56 ++++++++++--------- 1 file changed, 30 insertions(+), 26 deletions(-) diff --git a/web/app/static/js/modules/corpus_analysis/client/Client.js b/web/app/static/js/modules/corpus_analysis/client/Client.js index 4c7acc31..262c8f48 100644 --- a/web/app/static/js/modules/corpus_analysis/client/Client.js +++ b/web/app/static/js/modules/corpus_analysis/client/Client.js @@ -4,7 +4,7 @@ * It communicates with the server (e.g. connection or query) * and recieves data from it, if dynamicMode is true. * If dynamicMode is false, the client can also handle data that is already - * loaded and is not coming in in chunks. + * loaded and is not coming in, in chunks. */ class Client { constructor({corpusId = null, @@ -19,12 +19,11 @@ class Client { this.eventListeners = {}; this.connected = false; - /** - * Disable all console logging. + * Disables all console logging. * This is global. So every other log message in every other Class or * function used in conjunction with the client either logs or does not - * log depending on the logging flag. + * log depending on the logging flag. It is kind of hacky but not bad. * Credits to https://gist.github.com/kmonsoor/0244fdb4ad79a4826371e58a1a5fa984 */ if (!logging) { @@ -42,8 +41,11 @@ class Client { } console.info("Client initialized:", this); } - - // Registers one or more SocketEventListeners to the Client. + /** + * Registers one or more event listeners to the Client. Either socket or + * custom javascript events. Event listeners are class instances of + * ClientEventListener implemented further below. + */ setSocketEventListeners(eventListeners) { for (let eventListener of eventListeners) { this.eventListeners[eventListener.type] = eventListener; @@ -51,8 +53,10 @@ class Client { } /** - * Loads the SocketEventListeners so they will be triggered on their assigned - * type strings because they double as the socket event event names. + * Loads the event listeners that have been registered with the function + * above so that they will be triggered on their assigned + * type strings. Type strings double as the socket event event names or + * javascript custom event names. */ loadSocketEventListeners() { for (let [type, listener] of Object.entries(this.eventListeners)) { @@ -61,8 +65,10 @@ class Client { } /** - * This functions sends events to the View to trigger specific functions that - * are handleing the representation of data stored in the model. + * This functions emits the 'notify-view' custom javascript event. This + * triggers specific functions in the View depending on the caseIdentifier. + * The detail object can hold any type of data the View needs to know about + * to represent those to the user. */ notifyView(caseIdentifier, detailObject={}) { detailObject.caseIdentifier = caseIdentifier; @@ -71,14 +77,9 @@ class Client { document.dispatchEvent(event); } - // Registers a CorpusAnalysisDisplay object to the Client. - setDisplay(type, corpusAnalysisDisplay) { - this.displays[type] = corpusAnalysisDisplay; - } - /** - * Connects to the corpus analysis session for the specified corpus via - * socket.io. + * Connects to the corpus analysis session running on the server side for the + * specified corpus via socket.io. */ connect() { console.info('corpus_analysis_init: Client connecting to session via', @@ -86,6 +87,7 @@ class Client { this.socket.emit('corpus_analysis_init', this.corpusId); } + // Gets the meta data of the current corpus. getMetaData() { console.info('corpus_analysis_meta_data: Client getting meta data via', 'socket.emit.'); @@ -103,9 +105,9 @@ class Client { } /** - * Create results data either from all results or from all marked sub results - * Triggers emit to get full match context from server for a number of - * matches identified by their data_index. + * Requests results data either for, 'full-results', 'sub-results' or + * 'inspect-results' (resultsType). + * Gets full results for evere provided dataIndex (one match). **/ getResultsData(resultsType, dataIndexes, results) { let tmp_first_cpos = []; @@ -125,10 +127,12 @@ class Client { /** - * This class is used to create an SocketEventListener. + * This class is used to create an event listener listening for socket or + * javascript custom events. * Input are an identifying type string, the listener function and callbacks * which will be executed as part of the listener function. The identifying - * type string is also used as the socket event event identifier. + * type string is also used as the socket event or custom javascript event name + * identifier. */ class ClientEventListener { constructor(type, listenerFunction) { @@ -137,7 +141,7 @@ class ClientEventListener { this.type = type; } - // Registers callbacks to this SocketEventListener + // Registers callbacks to this ClientEventListener. setCallbacks(listenerCallbacks) { for (let listenerCallback of listenerCallbacks) { this.listenerCallbacks[listenerCallback.type] = listenerCallback; @@ -159,7 +163,7 @@ class ClientEventListener { ...listenerCallback.args); } } - // use this if you only want to execute a specific registered callback + // Executes a specific registered callback by provoding a type string. executeCallback(defaultArgs, type) { let listenerCallback = this.listenerCallbacks[type]; listenerCallback.callbackFunction(...defaultArgs, @@ -169,7 +173,7 @@ class ClientEventListener { /** * This class is used to create an ListenerCallback which will be registered - * to an SocketEventListener so the Listener can invoke the ListenerCallback + * to an ClientEventListener so the listener can invoke the associated * callback functions. */ class ListenerCallback { @@ -180,7 +184,7 @@ class ListenerCallback { } } -// export Classes from this module +// Export Classes from this module. export { Client, ClientEventListener,