Added first version of README.md

README.md

@@ -0,0 +1,151 @@
+# TANIA Web App
+
+This web app serves as a backend management system for the client, Juan Lugo (juan.ramirez3@upr.edu) which integrates both the Android and iOS apps. Some of the functionalities include creating experiences where students can enroll in through the mobile apps, creating questionnaires ("repertoires" of questions), creating moments out of those questionnaires, and creating milestones that can be used to track any trend on students' answers. Questionnaires and moments can be imported through an Excel sheet with a specified format or created from scratch directly from the 'experience' page. Moments, milestones and questions can be edited at will through the use of a calendar and two other pages. Results can be accessed through an "export" button and inspected through numerous different charts in the 'results' page. More, smaller functionalities and features lie within the web app.
+
+This guide is a project-wide overview of how each script communicates with each other and should be used to navigate through each different file in the project. More in-depth explanations of how each function and chunks of code work can be found in the files themselves. As this was developed mostly by Víctor Hernández (victor.hernandez17@upr.edu) backed by database overseen by Carlos Corrada (carlos.corrada2@upr.edu), any questions can be made to any of the aforementioned developers' emails.
+
+
+## Legend:
+`* <- Means name may change`
+`** <- Means input validation still hasn't been done`
+`*** <- Means styling still hasn't been finished`
+`**** <- Means not in use anymore`
+
+
+## Partials:
+Files used mostly for layout and importing styles and common images.
+- `header.php`
+- `footer.php`
+
+
+## Views:
+Files that the user gets to interact with (the "actual" frontend).
+- `index.php`
+> Login / landing page. Provides a brief overview of the project and contact info.
+- `home.php`
+> Provides a mechanism to create new Experiences. Also displays all of the user's Experiences. Provides a link to access all of the user's Questionnaires. Provides a link to Sign Out.
+- `viewExperience.php`
+> Provides all the info about a user's Experience. Has a calendar of events (that includes the start date, the end date, the Milestones, and the Moments). Lists the Questionnaires, Moments and Milestones (provides mechanism to create all of these too). Provides a mechanism to change the Experience's title and description.
+- `viewQuestionnaire.php`***
+> Provides all the info about a user's Questionnaire. Lists all of its Questions, along with a "**Delete**" button to delete a given Question **(this affects the Moments and the Results)**. Provides a mechanism to add a new Question to the Questionnaire.
+- `viewMoment.php`***
+> Provides all the info about a user's Moment. Lists all of its Questions, along with a "**Remove**" button to remove a given Question from the Moment. Provides a mechanism to add a new Question to the Moment **(from the Questionnaire it's associated to)**.
+- `questionnaires.php`\****
+> Lists all of the user's Questionnaires. Provides a mechanism to create a new one from scratch (the same one as in `viewExperience.php`). Provides a mechanism to import a new one from a `.csv `file (along with a "**Download Template**" button so that the user follows the suggested guidelines). Also provides a mechanism to "**Duplicate**" a given Questionnaire from one Experience to another (so that the user can reuse them in different Experiences).
+- `respuestas.php`*
+> Lists all of the Results of a given experience (i.e. the _scaled_ answers), along with **mean**, **stdev** and **percent change** (between pre-post, pre-tania, post-tania). Can filter through subcategories, categories and individual students.
+- `error.php`
+> Lets user know there has been an error. Mostly occurs when the user's session has expired (which is a 1 hour limit). Redirects to `login.php`.
+- `unauthorized.php`
+> Lets user know that his email is unauthorized to use TANIA and makes sure `$_SESSION` variables are unset/destroyed. Redirects to `login.php`. **NOTE:** The user's email **(and only the user's email)** has to be in the DB table `researcher` to be considered "registered". During first login, `callback.php` is in charge of retrieving the data from user's Google account.
+- `users.php`
+> Lets administrators add users and decide which other users are administrators.
+- `../enrollInExp.php`
+> Landing page for the students. Presents the necessary steps for a student to participate in an experience, along with TANIA logo, links to CDCC page, etc.
+
+
+## Configuration:
+Files used for database connection, login logic and other configurations.
+- `dbh.inc.php`
+> Database configuration file. Provides a `$connection` variable that is used throughout all other scripts.
+- `config.php`
+> Google OAuth2 configuration file.
+- `callback.php`
+> After the user logs in through Google, it receives the user's data and sets `$_SESSION` variables, as well as `$dbUserData` variable.
+- `checkLogin.php`
+> Checks if the appropriate `$_SESSION` variables are set so that the user can continue in the page. If they are not set (or if invalid), it redirects user to `error.php` or `unauthorized.php`.
+
+
+## Backend:
+Files used for database transactions. Most are named in `<action><Entity>.php` where the `action` is done __over__ an `entity`. Some are used for visualizations in other pages such as `respuestas.php`. Another is used for the calendar in `viewExperience.php`, and so on.
+- `export.php`**
+> Exports the Results from `respuestas.php` in `.csv` format.
+- `logout.php`
+> Logs user out (unsets/destroys `$_SESSION` variables).
+- `special.php`*
+> Populates dropdown (in `viewExperience.php`) with a Questionnaire's Questions (by specifying Questionnaire ID)
+- `special2.php`*
+> Gathers Moments, Milestones and other details from a given Experience, sending them out in JSON so that the Calendar (in `viewExperience.php`) gets populated with events (by specifying Experience ID).
+- `special4.php`*
+> Changes the StartDate of a given calendar event (Moment or Milestone) by specifying 1) the “event ID” and “event Type” separated by a '-', 2) the corresponding Experience ID, and 3) the event's new StartDate (in `viewExperience.php`).
+- `special5.php`*
+> Spits out JSON data for "Answer Rate" histogram, which indicates how many people have answered each moment (i.e. 5 people answered moment 1, while 7 people answered moment 3, etc.)
+- `special6.php`*
+> I THINK THIS IS NOT BEING USED...
+- `funciones.php`*
+> Functions used by `siCategoria.php`, `siPreguntas.php` and `siSubCategoria.php`.
+- `respuestasData.php`*
+> Used asynchronously by `respuestas.php` when changes in the table are made.
+- `siCategoria.php`*
+> Used asynchronously by `respuestas.php` when changes in the table are made.
+- `siPreguntas.php`*
+> Used asynchronously by `respuestas.php` when changes in the table are made.
+- `siSubCategoria.php`*
+> Used asynchronously by `respuestas.php` when changes in the table are made.
+- `insertExperience.php`
+- `updateExperience.php`
+- `insertQuestionnaire.php`
+- `updateQuestionnaire.php`
+- `importQuestionnaire.php`**
+- `duplicateQuestionnaire.php`
+- `insertMoment.php`
+- `updateMoment.php`
+- `insertMilestone.php`
+- `updateQuestion.php`
+- `insertQuestionToQuestionnaire.php`
+- `addExistingQuestionToMoment.php`
+- `removeQuestionFromMoment.php`
+- `deleteQuestionnaire.php`
+- `deleteMoment.php`
+- `deleteQuestion.php`
+- `addUser.php`
+- `makeManager.php`
+- `categoryBreakdown.php`
+> This script fetches how many people, for every category, have answered a given score and spits out a JSON with an array of category ID, category name, score and count.
+- `questionBreakdown.php`
+> This script fetches how many people, for every question, have answered a given score and spits out a JSON with an array of question ID, question premise, score and count.
+- `subcategoryBreakdown.php`
+> This script fetches how many people, for every subcategory, have answered a given score and spits out a JSON with an array of subcategory ID, subcategory name, score and count.
+
+
+## Styling:
+- `css/`
+> Compiled CSS from SASS files in folder `scss/`.
+- `scss/`
+> Uncompiled SASS files.
+
+
+## Images:
+- `img/`
+> Provides the photos used for `header.php`, `index.php`, `home.php` and `enrollInExp.php`.
+
+
+## Dynamicity:
+- `js/`
+> Folder that contains the javascript code for each "View" PHP script. The names are the same as their corresponding PHP scripts.
+
+
+## Testing/Prototyping:
+Used sparingly for testing backend and frontend code before moving it to a working script.
+- `test.php`
+- `testFrontEnd.php`
+
+
+## Old Code:
+Old files used for the alpha version of TANIA (EMA/MARLE) which are not in use currently. Created mostly by Coralys Cubero (coralys.cubero@upr.edu) from August 2018 to February 2019.
+- `old_code/`
+- `processes/old_code3`
+- `../old_code2`
+
+
+## Libraries:
+- `jQuery`
+> Mainly used for asynchronous requests in the server (in `home.php`, `viewExperience.php` and `respuestas.php`* ) as well as other features inside of Bootstrap.
+- `jQuery UI`
+> Used for inputs of type `date` and `datetime` in `home.php` and `viewExperience.php`.
+- `Bootstrap`
+> Mainly used for styling purposes.
+- `FullCalendar`
+> Used for the calendar in `viewExperience.php`.
+- `Chart.js`
+> Used for the charts in `respuestas.php`*.