From 3d2a6b8053600741046714d04994cf2f41cc83c9 Mon Sep 17 00:00:00 2001 From: Ivan Mattie Date: Fri, 20 Jan 2017 18:03:17 -0700 Subject: [PATCH 1/2] Added JSDOC documentation in the code --- src/ToastController.js | 126 ++++++++++++++++++++++++++++++++++++----- 1 file changed, 113 insertions(+), 13 deletions(-) diff --git a/src/ToastController.js b/src/ToastController.js index a6013a0..ffb9b76 100644 --- a/src/ToastController.js +++ b/src/ToastController.js @@ -1,4 +1,9 @@ (function(){ + /** + * Creates a new ToastController, which is a manager for Toasts. Should only + * ever be one of these on a page. + * @class + */ var ToastController = function(){ var body = document.getElementsByTagName("body")[0]; @@ -10,23 +15,46 @@ body.appendChild(this.container); }; - ToastController.prototype.openToast = function(data){ - var toast = new Toast(data.name, data.text, this); - - if(data.icon) { - toast.icon = data.icon; + /** + * Opens a new Toast based on the the configuration data passed in as a map + * + * @param {Object} config the configuration data to configure how the Toast + * is created + * + * @param {string} config.name the name of the Toast, to be used to + * reference it later + * + * @param {string} config.text the text to display inside the Toast + * + * @param {string=} config.icon the icon to display on the left side of the + * Toast + * + * @param {string=} config.className additional class that will be added to + * the Toast's classes + * + * @param {ToastPriority=} config.priority the level of priority that the + * Toast has, out of two possible priorities: ToastPriority.HIGH or + * ToastPriority.LOW + * + * @returns {Toast} The Toast that was created and opened + */ + ToastController.prototype.openToast = function(config){ + var toast = new Toast(config.name, config.text, this); + + if(config.icon) { + toast.icon = config.icon; } - if(data.delay) { - toast.delay = data.delay; + if(config.delay) { + toast.delay = config.delay; } - if(data.className) { - toast.className = data.className; + if(config.className) { + toast.className = config.className; } - if(data.priority) { - toast.priority = data.priority; + if(config.priority) { + toast.priority = config.priority; } toast.create(); @@ -36,12 +64,25 @@ return toast; }; + /** + * Closes an existing Toast given the Toast's name (assuming it exists) + * + * @param {string} name the name of the Toast set when calling openToast + */ ToastController.prototype.closeToast = function(name){ if(this.activeToasts[name]){ this.activeToasts[name].close(); } }; + /** + * Alias to open a "success" type Toast, which has a low priority, green + * background, and the Material "done" icon. + * + * @param {string} text the text to put inside the Toast + * + * @returns {Toast} + */ ToastController.prototype.success = function(text) { return this.openToast({ name: "sucess", @@ -51,6 +92,14 @@ }); }; + /** + * Alias to open an "error" type Toast, which has a high priority, red + * background, and the Material "error" icon. + * + * @param {string} text the text to put inside the Toast + * + * @returns {Toast} + */ ToastController.prototype.error = function(text) { return this.openToast({ name: "error", @@ -61,6 +110,14 @@ }); }; + /** + * Alias to open a "warning" type Toast, which has a high priority, yellow + * background, and the Materal "warning" icon. + * + * @param {string} text the text to put inside the Toast + * + * @returns {Toast} + */ ToastController.prototype.warn = function(text) { return this.openToast({ name: "warning", @@ -71,6 +128,20 @@ }); }; + /** + * Creates a new Toast object based on the configuration passed in. + * + * @class + * + * @param {string} name the name of the Toast (used programmatically, never + * displayed) + * + * @param {string} text the text to appear inside the Toast + * + * @param {ToastController} controller the controller that manages this + * Toast (so the Toast can tell its controller that it is going to destroy + * itself) + */ var Toast = function(name, text, controller){ this.name = name; this.text = text; @@ -83,6 +154,10 @@ this.delay = 5000; }; + /** + * Actually spawns the Toast's HTMLElement in the DOM, and starts the timer + * for it to dissapear. + */ Toast.prototype.create = function(){ var self = this; var textContainer = document.createElement("span"); @@ -121,6 +196,10 @@ }, this.delay); }; + /** + * Sets the primary element for the Toast to have the proper priority and + * ARIA attributes. + */ Toast.prototype.assignPriority = function() { if(this.priority === window.ToastPriority.HIGH) { this.element.setAttribute("role", "alert"); @@ -130,6 +209,11 @@ } }; + /** + * Builds the icon HTMLElement for the icon specified for the Toast + * + * @returns {HTMLElement} the "i" tag element that represents the icon + */ Toast.prototype.buildIcon = function() { var icon = document.createElement("i"); @@ -141,10 +225,19 @@ return icon; }; + /** + * Handler for "onclick" events fired on the Toast; will close the Toast + * when the Toast is clicked. + */ Toast.prototype.onClick = function(e){ this.close(); }; + /** + * Handler for "transitionend" events fired on the Toast; will destroy the + * Toast assuming that the Toast just closed and finished its closing + * animation. + */ Toast.prototype.transitionEnd = function(e){ if(!this.isOpen){ // destroy element and tell controller to forget about the Toast @@ -154,6 +247,10 @@ } }; + /** + * Opens the Toast (assumes that the Toast's DOM compontent has been + * generated). + */ Toast.prototype.open = function(){ var self = this; @@ -163,8 +260,11 @@ self.element.className = "toast open " + self.className; }); }; - - // Warning: close also destroys the Toast + + /** + * Closes the Toast. Warning: once the Toast is finished closing, it will + * destroy itself. + */ Toast.prototype.close = function(){ if(this.closed){ return; From 1e8309d98c46711741a51e195746d0adfdc5e8ee Mon Sep 17 00:00:00 2001 From: Ivan Mattie Date: Fri, 20 Jan 2017 18:09:35 -0700 Subject: [PATCH 2/2] Refactored code slightly --- src/ToastController.js | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/src/ToastController.js b/src/ToastController.js index ffb9b76..291dcff 100644 --- a/src/ToastController.js +++ b/src/ToastController.js @@ -5,12 +5,24 @@ * @class */ var ToastController = function(){ - var body = document.getElementsByTagName("body")[0]; - - this.container = document.createElement("div"); this.activeToasts = {}; this.iconBase = "material-icons"; + // Setup the container for Toasts + this.createContainer(); + }; + + /** + * Creates a hidden div on the page to contain Toasts inside of it. The div + * will be a child of the document body. + */ + ToastController.prototype.createContainer = function() { + if(this.container) { + return; + } + + const body = document.getElementsByTagName("body")[0]; + this.container = document.createElement("div"); this.container.id = "__toast_container"; body.appendChild(this.container); }; @@ -143,15 +155,15 @@ * itself) */ var Toast = function(name, text, controller){ - this.name = name; - this.text = text; - this.controller = controller; - this.isOpen = false; + this.className = ""; this.closed = false; + this.controller = controller; + this.delay = 5000; this.icon = false; + this.isOpen = false; + this.name = name; + this.text = text; this.priority = window.ToastPriority.LOW; - this.className = ""; - this.delay = 5000; }; /** @@ -260,7 +272,7 @@ self.element.className = "toast open " + self.className; }); }; - + /** * Closes the Toast. Warning: once the Toast is finished closing, it will * destroy itself.