From 378f0a8a74cab51543aa1a082ddc9bf420c94088 Mon Sep 17 00:00:00 2001 From: jzamora5 Date: Fri, 12 Feb 2021 20:24:23 -0500 Subject: [PATCH] Add documentation to XML based script --- xml-scripts.js | 100 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 100 insertions(+) diff --git a/xml-scripts.js b/xml-scripts.js index 5229a4b..35f9f88 100644 --- a/xml-scripts.js +++ b/xml-scripts.js @@ -1,5 +1,13 @@ $(document).ready(function () { // XML TO OBJECT LIST ===================================================== + + /** + * Transfrom an XML object to a regular JSON like object + * @xml {xml_object} xml to be transformed + * @key {string} value passed if a specific query must be + * done in XML + * @return {Array} list of parsed data + */ function XMLtoObjList(xml, key) { let list = []; let dic = {}; @@ -42,6 +50,11 @@ $(document).ready(function () { } // Quotes =============================================================== + /** + * Creates a carousel item and appends it to the DOM + * @data {Array} List of data to be displayed as Quotes + * @return {undefined} No return + */ function displayQuotes(data) { data = XMLtoObjList(data, "quote"); let classItem = ""; @@ -76,6 +89,12 @@ $(document).ready(function () { // END OF displayQuotes } + /** + * Modifies to logic of bootstrap carousel in order for + * it to move 1 slide at a time + * @id {string} Id of a carousel item slide + * @return {undefined} No return + */ function slideOne(id) { $(`#${id} .carousel-item`).each(function () { let minPerSlide = 4; @@ -96,6 +115,11 @@ $(document).ready(function () { }); } + /** + * Creates the string equivalent of a card element in bootstrap + * @cardData {object} An object containing data for creating the card + * @return {string} string equivalent of a card element in bootstrap + */ function createCard(cardData) { let starState = ""; let starString = ""; @@ -155,6 +179,12 @@ $(document).ready(function () { // END OF createCard } + /** + * Creates cards and attaches them to the DOM in order to display + * the Popular Videos section + * @data {Arrray} list of data for creating cards + * @return {undefined} no return + */ function displayPopular(data) { data = XMLtoObjList(data, "video"); let classItem = ""; @@ -175,6 +205,12 @@ $(document).ready(function () { // END OF displayPopular } + /** + * Creates cards and attaches them to the DOM in order to display + * the Latest Videos section + * @data {Array} list of data for creating cards + * @return {undefined} no return + */ function displayLatest(data) { data = XMLtoObjList(data, "video"); let classItem = ""; @@ -195,6 +231,12 @@ $(document).ready(function () { // END OF displayLatest } + /** + * Retrieves the needed data of the search bar in the DOM + * the popular section + * @return {object} An object containing the different arguments of search + * in lowercase and without spaces + */ function searchObject() { let searchObj = { q: $("#keywords-input").val(), @@ -205,6 +247,12 @@ $(document).ready(function () { return searchObj; } + /** + * Creates cards and attaches them to the DOM in order to display + * the popular section + * @data {Array} list of data for creating cards + * @return {undefined} no return + */ function searchRequest() { let searchObj = searchObject(); let $results = $("#results-items"); @@ -216,6 +264,12 @@ $(document).ready(function () { } } + /** + * Returns title to original condition with corresponding + * caps and spaces + * @title {string} title to be parsed + * @return {string} parsed title + */ function parseTitle(title) { if (title) { title = title.charAt(0).toUpperCase() + title.slice(1).replace("_", " "); @@ -223,6 +277,13 @@ $(document).ready(function () { return title; } + /** + * Creates the dropdown menu with the corresponding options from the api + * @list {Array} list of options to be displayed + * @$DOMElement {list} DOM Element to attach the menu to + * @$titleElement {list} corresponding title element in search bar of DOM + * @return {undefined} no return + */ function displayDropdown(list, $DOMElement, $titleElement) { if (list.length) { for (let l of list) { @@ -239,6 +300,11 @@ $(document).ready(function () { } } + /** + * Removes unnecesary nodes in XML object + * @data {xml_object} XML object + * @return {xml_object} cleaned xml object + */ function cleanXML(data) { $(data).find("topics").remove(); $(data).find("sorts").remove(); @@ -247,6 +313,12 @@ $(document).ready(function () { return data; } + /** + * Displays the whole search section in dom + * @data {object} object containing information + * about the topics and sort options + * @return {undefined} no return + */ function displaySearch(data) { let title; let topics = XMLtoObjList(data, "topic"); @@ -275,6 +347,11 @@ $(document).ready(function () { }); } + /** + * Shows all of the videos, obtained after request to API, in DOM + * @data {object} object containing result from API response + * @return {undefined} no return + */ function displayResults(data) { let courses = XMLtoObjList(data, "course"); if (!courses) return; @@ -296,6 +373,12 @@ $(document).ready(function () { } } + /** + * Calls the needed functions in order to correctly display + * the search options in dom and results from API response + * @data {data} object containing data from API response + * @return {string} parsed title + */ function displaySearchAndResults(data) { displayResults(data); displaySearch(data); @@ -303,6 +386,13 @@ $(document).ready(function () { // END OF displayResults } + /** + * Function to show loader when waiting for API response + * @active {boolean} indicates whether loader should be displayed or + * removed + * @id {string} Id of DOM object to attach loader to + * @return {string} parsed title + */ function displayLoader(active, id) { if (active) { let $loader = $(`
`); @@ -315,6 +405,16 @@ $(document).ready(function () { // END OF displayLoader } + /** + * Function to make GET request to API + * @url {string} url of API endpoint + * @callback {function} callback function to be executed + * and that depends on the section of the web page which is being + * generated by JS + * @id {string} Value needed to display loader + * @data {object} object to send in API request + * @return {string} parsed title + */ function requestData(url, callback, id, data = {}) { displayLoader(true, id);