diff --git a/.vuepress/config.js b/.vuepress/config.js index 926acdf..17b5675 100644 --- a/.vuepress/config.js +++ b/.vuepress/config.js @@ -4,16 +4,21 @@ module.exports = { "We're unifying UofT's course data, and using it to build tools such as a course guide and timetable planner.", themeConfig: { logo: "/logo.png", - repo: "utm-hacklab/VIAplanner", - editLinks: true, - editLinkText: "Edit on Github!", - lastUpdated: "Last Updated", nav: [ { text: "Home", link: "/" }, - { text: "Course API", link: "/course-api/" }, - { text: "Timetable Planner", link: "/timetable-planner/" }, - { text: "Course Guide", link: "/course-guide/" }, + { + text: "VIAtimetable", + items: [ + { text: "Front End", link: "/via-timetable/front-end/" }, + { text: "API", link: "/via-timetable/api/" }, + { text: "Algorithm", link: "/via-timetable/algorithm/" }, + { text: "State Management", link: "/via-timetable/state-management/"}, + ], + }, + { text: "VIAcalendar", link: "/via-calendar/" }, + { text: "VIAevent", link: "/via-event/" }, { text: "Application", link: "https://viaplanner.ca/" }, + { text: "Github Repo", link: "https://github.com/VIAplanner" }, ], }, }; diff --git a/README.md b/README.md index a3e6571..d6cbf98 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ home: true heroImage: /logo-with-text.png heroText: tagline: VIAplanner is a tool designed by students at the University of Toronto to help the community. We desire to enhance the course selection process. -footer: MIT Licensed +footer: GNU V2 Licensed --- @@ -18,9 +18,9 @@ When you enter a well-run tech organization like Google, you’re met with a sui These tools were created by Googlers for Googlers. UofT students could make use of tools made by other UofT students that would allow them to do things like: -- Suggest timetables that optimize for their preferred timings -- Plan for courses based on course evaluation metrics that they care about -- Write plugins to expand the core functionality with their creative ideas +- Suggest timetables that optimize for their preferred timings +- Generate calendar based on student's timetable and relavent events +- A platform that offers various club events Fundamental problem we are trying to solve : @@ -32,14 +32,18 @@ Futhermore, this will improve UofT's reputation since this tool will modernize a ## Implementation -The first areas of student experience we're looking to enhance are course selection and timetable planning. +### VIA Timetable +VIA Timetable is a module under VIA planner that aims to provide the best course selection experience. Unlike other tools such as Griddy or UTM Timetable, our users **do not** need to select the times for their courses, they simply need to search and click on their desired courses. With the combined power of our algorithm and comprehensive database of all 3 UofT campuses' courses, we are able to generate a conflict-free timetable. -We envision the following user journey for a student: +You can learn more about it [here](/via-timetable/front-end) -![User Journey](./course-guide/user-journey.png) +### VIA Calendar +VIA Calendar is a module under VIA planner that serves as an extension of VIA Timetable. We envision the user being able to connect their google calendar and directly move their timetable from VIA Timetable into their calendar. Other features could be sharing your timetable with other VIA planner users. -The two components we identified to build this system are the [Course Guide](/course-guide/) and the [Timetable Planner](/timetable-planner/) +You can learn more about it [here](/via-calendar/) -We then identified that the two components in our system required data that was scattered across various UofT web services. Some of this data had to be scraped, while others were available through APIs. +### VIA Event -The third component that emerged was the [Unified Backend](/unified-backend/). This API would provide our apps with unified access to the scattered UofT course data. This API would also allow students to make use of the data to write plugins to expand the core functionality with their creative ideas. \ No newline at end of file +VIA Event is a module under VIA planner that aims to displays all events at UofT. We envision similar functionality to platforms such as Evenbrite where users could view, add, comment, and share different events. + +You can learn more about it [here](/via-event/) \ No newline at end of file diff --git a/course-api/backend-architecture.png b/assets/API-pics/backend-architecture.png similarity index 100% rename from course-api/backend-architecture.png rename to assets/API-pics/backend-architecture.png diff --git a/assets/User_Experience.png b/assets/User_Experience.png new file mode 100644 index 0000000..ac6ff8d Binary files /dev/null and b/assets/User_Experience.png differ diff --git a/assets/VIAtimetable-pics/VuexRoadmap.png b/assets/VIAtimetable-pics/VuexRoadmap.png new file mode 100644 index 0000000..fec052b Binary files /dev/null and b/assets/VIAtimetable-pics/VuexRoadmap.png differ diff --git a/assets/VIAtimetable-pics/courseSearch.JPG b/assets/VIAtimetable-pics/courseSearch.JPG new file mode 100644 index 0000000..539754e Binary files /dev/null and b/assets/VIAtimetable-pics/courseSearch.JPG differ diff --git a/assets/VIAtimetable-pics/delievery.JPG b/assets/VIAtimetable-pics/delievery.JPG new file mode 100644 index 0000000..4618c6e Binary files /dev/null and b/assets/VIAtimetable-pics/delievery.JPG differ diff --git a/assets/VIAtimetable-pics/delievery.PNG b/assets/VIAtimetable-pics/delievery.PNG new file mode 100644 index 0000000..f01a7ee Binary files /dev/null and b/assets/VIAtimetable-pics/delievery.PNG differ diff --git a/assets/VIAtimetable-pics/img1.gif b/assets/VIAtimetable-pics/img1.gif new file mode 100644 index 0000000..581f546 Binary files /dev/null and b/assets/VIAtimetable-pics/img1.gif differ diff --git a/assets/VIAtimetable-pics/invalid.JPG b/assets/VIAtimetable-pics/invalid.JPG new file mode 100644 index 0000000..34b3a6d Binary files /dev/null and b/assets/VIAtimetable-pics/invalid.JPG differ diff --git a/assets/VIAtimetable-pics/invalid.PNG b/assets/VIAtimetable-pics/invalid.PNG new file mode 100644 index 0000000..d1b740f Binary files /dev/null and b/assets/VIAtimetable-pics/invalid.PNG differ diff --git a/assets/VIAtimetable-pics/slide4.gif b/assets/VIAtimetable-pics/slide4.gif new file mode 100644 index 0000000..70cf729 Binary files /dev/null and b/assets/VIAtimetable-pics/slide4.gif differ diff --git a/assets/VIAtimetable-pics/startTimetable.JPG b/assets/VIAtimetable-pics/startTimetable.JPG new file mode 100644 index 0000000..8c72d73 Binary files /dev/null and b/assets/VIAtimetable-pics/startTimetable.JPG differ diff --git a/assets/VIAtimetable-pics/startTimetable.PNG b/assets/VIAtimetable-pics/startTimetable.PNG new file mode 100644 index 0000000..96b83cb Binary files /dev/null and b/assets/VIAtimetable-pics/startTimetable.PNG differ diff --git a/course-guide/Course_Selecting_State.png b/course-guide/Course_Selecting_State.png deleted file mode 100644 index 6053a4c..0000000 Binary files a/course-guide/Course_Selecting_State.png and /dev/null differ diff --git a/course-guide/Program_Choosing_state.png b/course-guide/Program_Choosing_state.png deleted file mode 100644 index 502543a..0000000 Binary files a/course-guide/Program_Choosing_state.png and /dev/null differ diff --git a/course-guide/README.md b/course-guide/README.md deleted file mode 100644 index d3c4950..0000000 --- a/course-guide/README.md +++ /dev/null @@ -1,398 +0,0 @@ ---- -sidebar: auto ---- - -# Course Guide - -## Vision -The Course Guide component helps students have a better understanding of what the right courses for them are. - -The Course Guide generates a list of recommend courses based on the student's year and programs from students. - -## Overview - -The course guide covers the program and course selection of the user's journey through our system. - -![User Joruney](./user-journey.png) - - -### Program Selection - -After a user selects their year, they're able to browse through the list of programs available to them, adding programs to their program cart as they see fit. - -__User Journey Statechart__ -![program-selecting-chart](./Program_Choosing_state.png) - -__Program Selection Concept Design__ -![program-selecting-figma](./figma_pic.png) - -### Course Selection - -With the programs selected, the user now moves to the course selection stage. Here, the user can add courses to their course cart by exploring courses via the search bar or consulting our _Recommended Courses_ UI component's suggestions. - -__User Journey Statechart__ - ![course-selecting-chart](./Course_Selecting_State.png) - -__Course Selection Concept Design__ -![course-selecting-figma](./figma_course_pic.png) - - -## Terminology - -### Program -Contains all the information for a program, refer to [Course API](https://uoftcoursetools.tech/course-api/) - -### Subject -Contains an array of Programs, ex: Anthropology contains Specialist Program ERSPE0105 -Anthropology (Science), Major Program ERMAJ0105 Anthropology (Science), and Minor Program ERMIN1775 -Anthropology (Arts). - -### Subject Group -Contains an array of Subjects, subjects are grouped into bigger groups, like the field of study. Ex: Biology is a SubjectGroup that contains Biology, Biology-Health Science, Biotechnology, Ecology & Evolution, Molecular Biology and Paleontology. - -### Course -Contains all the information for a course, refer to [Course API](https://uoftcoursetools.tech/course-api/) - -### CourseGroup -Contains a group of Courses. Courses are grouped according to their course codes, ex: all the courses that start with "CSC" are under the Computer Science group - - -## Component Breakdowns - -The course guide involves the most UI interaction with the user, thus it is important to keep track of the abstract design. - - -## Part 1: Program Choosing - -### MyProgramsList - -The list of programs the user has added. - -```js -MyProgramsList{ - data:{ - programs: [Program]//array of programs the user has added - }, - methods:{ - deleteProgram(program) // triggered when pressing delete on a program - }, - components:{ - [ChosenProgramTile] //each tile is a program in the list and is clickable - } -} -``` - -### ChosenProgramTile - -The component for the programs listed in MyprogramsList - -```js -ChosenProgramTile{ - data: { - programName: String //The name of the program this tile represents - subject: Subject //which subject this program belongs in - }, - methods: { - loadSubject(subject), /*displays the programs in the same subject as - selected_program in the "programCardsPanel",*/ - delete() //remove this program when the "x" button is clicked - }, - components: { - DeleteButton - } -} -``` - -### SubjectsList - -The SubjectsList is a list of all the subject names offered at UTM. The user can browse through it and click a subject in this list to view all the programs of that subject. - -```js -SubjectsList{ - data:{ - searchMatchingSubjects: [Subject] /*The subjects that have a program that - matches the search query*/ - showingGroups: [SubjectGroup] //array of subject groups that still shows in this list - }, - components:{ - [SubjectTile]: //an array of subject names that can be clicked - } -} -``` - -### SubjectTile - -The component for the subjects in SubjectsList - -```js -SubjectTile{ - data: { - subject: Subject, //the subject this tile represents - highlighted: boolean - }, - methods: { - loadSubject(subject) /*displays the programs in the same subject as - selected_program in the "programCardsPanel",*/ - } -} -``` - -### ProgramCardsPanel - -The component that displays the detailed information of each program in a subject and allows the user to add a program to My_Programs_List - -```js -ProgramCardsPanel { - data: { - subject: Subject //The subject - }, - methods:{ - setSubject(subject) //Save the specified subject into data.subject to load programCards - }, - components:{ - [ProgramCard] //each individual program's information - } -} -``` - -### ProgramCard - -The ProgramCard displays all the information about a specific program, and a button to add it - -```js -ProgramCard { - data:{ - program: Program //The program this card represents - }, - methods: { - /*The required courses string for a certain year contains course codes - that refer to a course, we need a regex to recognize the course code pattern and transform - each of them into a CourseLink component that can be clicked to pop up a course info frame.*/ - }, - components:{ - AddProgramButton, //The "Add" button - [CourseLink] //each mention of a course code under required courses is a CourseLink - } -} -``` - -### CourseLink - -The course code of a course, clicking on it opens CourseInfoPopup - -```js -CourseLink { - data:{ - course: Course //The course this component links to - }, - methods: { - openPopup() //Triggered when this component is clicked, create a new instance of the pop up frame - } -} -``` - -### ProgramSearchBar - -The user can search for a program by NAME - -The search results are shown by the shortening of the SubjectsList - -Only the groups of subjects that contain at least one subject that contains at least -one program that matches the search query will remain in the SubjectsList - -The subjects that contain at least one program that matches the search query will be highlighted -for the user to see and click into - -The search can only be canceled by clearing the search box, in which case the SubjectsList will -be restored in full - -```js -ProgramSearchBar{ - data:{ - query: String, //The current search query - }, - methods:{ - search(query) /*Calls search for query in back-end and updates SubjectsList.showingGroups - and SubjectsList.searchMatchingSubjects - Better emit an event up to the main application to call a methods that does - all that*/ - }, -} -``` - -## Part 2: Course Choosing - -### CourseGroupsList - -The list of all the groups of courses offered at UTM, ex: Anthropology, Astronomy - -```js -CourseGroupsList{ - data: { - groups: [CourseGroup], //Array of all the courseGroups - expandedGroup: CourseGroup /*The selected course group is highlighted and expanded - in the CourseList*/ - }, - components:{ - [CourseGroupTile] //An array of course group names that can be clicked - } -} -``` -### CourseGroupTile - -The component for a single course group in CourseGroupsList - -```js -CourseGroupTile{ - data: { - groupName: String //The name of the course group this tile represents - highlighted: Boolean - }, - methods: { - loadCourseGroup() /*load the courses in this group into the course list by - passing in the groupName*/ - } -} -``` - -### CourseList - -The list shows all the courses in a specific course group, all the courses in one group has -course codes that start with the same 3 letters, ex: CSC, MAT - -```js -CourseList { - data: { - courses: CourseGroup //The courses in this list - }, - methods: { - loadCourses(groupName) //Searches the backend for the CourseGroup with the given groupName - }, - components: { - [CourseTile] //Each tile represents a course - } -} -``` - -### CourseTile - -The component for a single course in MyCoursesList, RecommendedList, and CourseList - -```js -CourseTile { - data: { - course: Course, //The course this tile represents - state: int /* What is the parent of this tile, - CourseList: has no extra buttons - MyCoursesList: has delete button while hovering - RecommendedList: has add button while hovering*/ - }, - methods: { - courseClicked(), //pop up course info frame - deleteCourse(), //If delete button is clicked, remove this course from MyCoursesList - addCourse(), /*If add button is clicked, add this course to My CoursesList and Remove - it from RecommendedList*/ - }, - components: { - //Depending on the state - AddCourseButton, - DeleteCourseButton - } -} -``` - -### MyCoursesList - -The list of courses the user has selected for this year - -```js -MyCoursesList { - data: { - myCourses: [Course], //The courses the user has added - }, - methods: { - addCourse(Course), //Adds the specified course to myCourses - removeCourse(Course), //Removes the specified course from myCourses - }, - components: { - [CourseTile] - } -} -``` - -### RecommendedList - -The list of courses recommended to the user based on their year of study and their -chosen program(s) - -```js -RecommendedList { - data: { - recommendedCourses: [Course], //Array of recommended courses - }, - methods: { - loadRecommendedCourses() /*Looks at the year of study, selected program(s), and - what's already in MyProgramsList to determine a list of - recommended courses*/ - removeCourses(Course), /*Removes the specified course from recommendedCourses (when - the user adds it)*/ - }, - components: { - [CourseTile], - AddAllButton //There is a button for adding all of the courses in this list at once - } -} -``` - -### CourseInfoPopUp - -The pop-up frame what pops up whenever a course is clicked for detailed information - -```js -CourseInfoPopup { - data: { - added: Boolean //Whether this course in my MyCoursesList - course: Course //The course which this pop-up frame is displaying info for - }, - methods: { - addCourse(), //Adds this course to MyCoursesList - removeCourse(), //Removes this course from MyCoursesList - }, - components: { - CourseLinks, //references to other courses, click to open another pop-up - AddCourseButton, //Depending on added state - RemoveCourseButton, //Depending on added state - ExitButton, //To close the pop-up - } -} -``` - -### CourseSearchBar - -The search bar allows the user to search for a course by the COURSE CODE. - -The search results are in a drop-down frame under the search bar, the drop- -down frame has a limited size, any overflowing search results can be viewed -by scrolling in the drop-down frame. - -The search results are also CourseTile Components that can be clicked to -pop-up a course info frame - -The search can be canceled by clicking elsewhere outside the search bar - -```js -CourseSearchBar { - data: { - query: String, //The current search query - results: [Course] //The courses that match the search query - }, - methods: { - search(query), /*Searches the back end for courses with course codes that - match the query and updates results*/ - clear() //Clears the search box and results drop down if search is canceled - }, - components: { - [CourseTile] //CourseTile components each as a search result in the drop-down - } -} -``` \ No newline at end of file diff --git a/course-guide/figma_course_pic.png b/course-guide/figma_course_pic.png deleted file mode 100644 index 8626637..0000000 Binary files a/course-guide/figma_course_pic.png and /dev/null differ diff --git a/course-guide/figma_pic.png b/course-guide/figma_pic.png deleted file mode 100644 index 0d5f595..0000000 Binary files a/course-guide/figma_pic.png and /dev/null differ diff --git a/course-guide/user-journey.png b/course-guide/user-journey.png deleted file mode 100644 index a96915b..0000000 Binary files a/course-guide/user-journey.png and /dev/null differ diff --git a/timetable-planner/README.md b/timetable-planner/README.md deleted file mode 100644 index 17db904..0000000 --- a/timetable-planner/README.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -sidebar: auto ---- -# Timetable Planner - -A web app that helps UofT students plan their courses to generate their optimal timetable. - -The timetable planner allows students to enter their course load and get back a timetable that fits their needs. The vision for the timetable planner includes taking student preferences into account such as: - -- How early students wish to start and end classes -- What days students would like to take off -- What times students would prefer gap time and breaks - - -## Overview - -![timetable-journey](./Timetable-journey.png) - -Once the user selects the courses from the Course Guide: - -![coursechosing](./coursechosing.png) - -The user views the timetable: - -The timetable will display whether or not if the selected courses have a valid time, that is no conflict for all courses. - - - Valid: - -![timetable](./timetable.png) - - - Invalid: - -![error1](./error1.png) - -There are serveral preferences that the user can select to optimize the timetable: - -![timetableconstraint](./timetableconstraint.png) - - - - Minimize/Maximize idle time: The user can maximize or minimize the gap time between courses. - - Days off: The user can select the day(s) off so there will be no course appear on that day. - - Avoid Morning/Evening Class: The user can choose whether if they want to have courses in the morning or evening. - -The timetable will return invalid and displays a message if the constraints are unreachable. - -![error2](./error2.png) - -The user can also choose to lock certain course times. - -When preferences are made, those times will not be changed. - -![lock1](./lock1.png) - -after a course is locked and a preference is being made: - -![lock2](./lock2.png) - -## Roadmap for the Timetable Algorithm - -The timetable algorithm takes in a set of course names and transforms into a list of timetables. Then the user can optimize the timetable to fit their preference. - -The algorithm starts out by checking if the given sections conflict with each other. The algorithm will return true or false depending on whether or not a conflict exists. - -After checking for basic validity, we can optimize our timetable by adding constraints to it. - -The algorithm then takes in an invalid time argument that inputs from the user's preference times off. - -The algorithm then implements an idle time function which takes in a set of valid timetable and returns the max and the min idle time depend on the user's preference. - -The algorithm then stores the user's locked courses in a list which will stay in position despite future optimization. - -### Checking for Conflicts - -Before any optimization, the algorithm checks if it is possible to make a timetable out of the given courses by checking the conflict between the course times. - -**Pseudocode** -```js -/** - * - * @param timetable: A map of day to timeSections - {"MONDAY": [time_sections], ...} - * - */ -function overlap(timetable){ - for day in timetable - if the times of the day overlaps each other - return false - return true -} -``` - -### Times Off - -The user can input their desired times off, such as day off or morning/evening off, the algorithm reruns the conflict check and returns valid timetable with the invalid times. - -**Psedocode** -```js -/** - * - * @param courseList: A list of course sections - {"CSC108H5FLEC0101": {"MONDAY":[Time Section], ...}, ...} - * @param timesOff: A map of day to TimeSections of times off - {"MONDAY":[Time Sections], ...} - * - */ -function bucketCourseByDay(courseList, timesOff){ - - for course in courseList - append course to timetable - for timesOffBlock in timesOff - append timesOffBlock to timetable - check if valid or not by overlap function - -} -``` - - - -### Maximize or Minimize Idle Time - -The user can choose to maximize or minimize their idle time at school, which is the time gaps between classes each day. The algorithm compares the total idle time in each timetable given and returns the user's preference. - -**Pseudocode** - -```js -/** - * - * @param setTimetable: A list of timetable - [{"MONDAY":[Time Sections], ...}] - * @param maxOrMin: A string - "MAX"/"MIN" - * - */ -function idleTime(setTimetable, maxOrMin){ - - for timetable in setTimetable - sum up all the idle time and store the index - check for the max and min of the idletimes - return based on maxOrMin - -} -``` - -### Locked Time Sections - -The user can lock the section(s) they prefer to stay the same while processing other optimizations. The algorithm stores the locked section in a list, when processing other optimization, the list is being compared and put in to the new timetable to ensure timetable includes the locked section. - - - - - diff --git a/timetable-planner/Timetable-journey.png b/timetable-planner/Timetable-journey.png deleted file mode 100644 index 60e3925..0000000 Binary files a/timetable-planner/Timetable-journey.png and /dev/null differ diff --git a/timetable-planner/Timetableroadmap.png b/timetable-planner/Timetableroadmap.png deleted file mode 100644 index 47398fe..0000000 Binary files a/timetable-planner/Timetableroadmap.png and /dev/null differ diff --git a/timetable-planner/coursechosing.png b/timetable-planner/coursechosing.png deleted file mode 100644 index f2b941f..0000000 Binary files a/timetable-planner/coursechosing.png and /dev/null differ diff --git a/timetable-planner/courseguide_to_timetable.png b/timetable-planner/courseguide_to_timetable.png deleted file mode 100644 index 7d0c87d..0000000 Binary files a/timetable-planner/courseguide_to_timetable.png and /dev/null differ diff --git a/timetable-planner/error1.png b/timetable-planner/error1.png deleted file mode 100644 index 367b234..0000000 Binary files a/timetable-planner/error1.png and /dev/null differ diff --git a/timetable-planner/error2.png b/timetable-planner/error2.png deleted file mode 100644 index c78f7b8..0000000 Binary files a/timetable-planner/error2.png and /dev/null differ diff --git a/timetable-planner/lock1.png b/timetable-planner/lock1.png deleted file mode 100644 index e3c4da0..0000000 Binary files a/timetable-planner/lock1.png and /dev/null differ diff --git a/timetable-planner/lock2.png b/timetable-planner/lock2.png deleted file mode 100644 index 9d002c9..0000000 Binary files a/timetable-planner/lock2.png and /dev/null differ diff --git a/timetable-planner/timetable.png b/timetable-planner/timetable.png deleted file mode 100644 index 12d2853..0000000 Binary files a/timetable-planner/timetable.png and /dev/null differ diff --git a/timetable-planner/timetableconstraint.png b/timetable-planner/timetableconstraint.png deleted file mode 100644 index c2870eb..0000000 Binary files a/timetable-planner/timetableconstraint.png and /dev/null differ diff --git a/via-calendar/README.md b/via-calendar/README.md new file mode 100644 index 0000000..e69de29 diff --git a/via-event/README.md b/via-event/README.md new file mode 100644 index 0000000..e69de29 diff --git a/via-timetable/algorithm/README.md b/via-timetable/algorithm/README.md new file mode 100644 index 0000000..37d7fce --- /dev/null +++ b/via-timetable/algorithm/README.md @@ -0,0 +1,49 @@ +--- +sidebar: auto +--- +# Timetable Algorithm + +The algorithm behind VIAtimetable that helps UofT students plan their courses by generating a optimal timetable. + +The timetable planner allows students to enter their course load and get back a timetable that fits their needs. The functions for the timetable planner are: +- How early students wish to start and end classes +- What days students would like to take off +- What times students would prefer gap time and breaks +- Preference on the delievery method (if the options are available) + +## Implementation of the Timetable Algorithm + +The timetable algorithm takes in a set of course and generate if possible, a valid timetable with the earliest time available. Then the user can optimize the timetable to fit their preference. + +The algorithm starts out by seperating the courses into fall and winter terms and generate a timetable for each term. +(_The reason to having functions to generate timetable with only practicals and tutorials is simply because there are courses with only such sections_) + +The generating algorithm is quite complicated and the concept will be demonstrated below. + +### Constraints: + +For the timetable to know which time interval is locked, we treat the interval as a course section. So the algorithm will take in consider of the locked time and will not place any other course section into the space. + +Since lock sections of a course is determined, the algorithm filters out to only the section locked, so it takes the highest priority in the timetable since its the only section available. + +As the algorithm adds the course from beginning of the course list to the end, applying preference of online or in-person of the courses will be sorting the list. + +### Algorithm: + +_Developer note: The algorithm may seems complicated with all the nested loop and recursive calls, but it is mainly similar code for lecture sections, practical secions, and tutorial secions. So once you understand how it works for the first layer, then the rest is the same._ + +**Recursive Case:** +The algorithm starts from searching for the first appearance of a course with lecture section. While such course is not the last course in the list (if it does, the index will be -1), for each lecture section in the course (_.some() function call_), a list containning the current combination of sections (now is empty) will append the section. +In the end of this case we will call the function itself again with the first lecture section being recorded and with a starting index from the course. This index will make the next search on course with lectures searching after the current course. + +**Base Case:** +Now we are at the last course with the lecture sections, we can now start to put the sections we stored previously with the current course's section into the timetable. Then the algorithm will check if this is a valid timetable or not by looking for conflict, if it does appear to have atleast one conflict between 2 sections, then we will reset the timetable to empty and adds the next lecture section of this course into the list and check again(If all section of this course conflicts with the previous added sections from other courses, then it will adds the next section from the last course before the current one). + +Now we got a timetable with lecture section which is good! We can move on to practical sections, if there are any in the courses, or tutorial sections. Adding the practical and tutorial sections works excactly the same as the lecture sections, but when we are reseting the timetable, we will be reseting to the one with only lecture sections instead of an empty timetable. + +Once the algorithm finds a timetable that includes every type of sections from all the courses, it will stop the iteration and return. The timetable is defined as a local variable in the whole function and its being updated through the above process, so we will return this timetable after all. \ No newline at end of file diff --git a/course-api/README.md b/via-timetable/api/README.md similarity index 90% rename from course-api/README.md rename to via-timetable/api/README.md index 0735a88..4d24293 100644 --- a/course-api/README.md +++ b/via-timetable/api/README.md @@ -8,13 +8,13 @@ Welcome to the VIAplanner API. The API is written with Express to provide maximu **Notes:** -1. The API is limited to **only** VIAplanner developers. Thus, an API key is required. The reason for doing so is to maximize performance for our timetable planner -2. Currently, the API only contains UTM data. However, we will expand it in the future to house UTSG and UTSC data as well +1. The API is limited to **only** VIAplanner developers. The reason for doing so is to maximize performance for our timetable planner +2. Currently, the API now contains information for all 3 UofT campuses 3. The API is still under development. Thus, the routes are likely to change -4. If you wish to use this API, please contact us at our [GitHub](https://github.com/UTM-Hacklab/VIAplanner) +4. If you wish to use this API, please contact us at our [GitHub](https://github.com/VIAplanner/via-timetable) ## High-level overview -![](./backend-architecture.png) +![](../../assets/API-pics/backend-architecture.png) ## Query Guide @@ -23,7 +23,7 @@ https://api.viaplanner.ca (this will take you to the docs) ### Get all courses **method:** get
-**usage:** https://api.viaplanner.ca/courses?api_key=api_key
+**usage:** https://api.viaplanner.ca/courses
**schema:** see [**Data Structure 9**](#_9-all-courses)
**return value:** - success: an array containing objects of all courses in the data base @@ -31,7 +31,7 @@ https://api.viaplanner.ca (this will take you to the docs) ### Get a courses **method:** get
-**usage:** https://api.viaplanner.ca/courses/courseCode?api_key=api_key
+**usage:** https://api.viaplanner.ca/courses/courseCode
**schema:** see [**Data Structures 1-3**](#_1-course)
**return value:** - success: an object containing the data of the specified course @@ -39,7 +39,7 @@ https://api.viaplanner.ca (this will take you to the docs) ### Get the search bar value **method:** get
-**usage:** https://api.viaplanner.ca/courses/searchbar?api_key=api_key
+**usage:** https://api.viaplanner.ca/courses/searchbar
**schema:** see [**Data Structure 8**](#_8-course-search-bar)
**return value:** - success: an array containing objects with the courseCode and name of every course in the database @@ -47,7 +47,7 @@ https://api.viaplanner.ca (this will take you to the docs) ### Create a courses **method:** post
-**usage:** https://api.viaplanner.ca/courses?api_key=api_key
+**usage:** https://api.viaplanner.ca/courses
**schema:** see [**Data Structures 1-3**](#_1-course)
**return value:** - success: an object with a message saying the course was created diff --git a/via-timetable/front-end/README.md b/via-timetable/front-end/README.md new file mode 100644 index 0000000..2b99764 --- /dev/null +++ b/via-timetable/front-end/README.md @@ -0,0 +1,36 @@ +--- +sidebar: auto +--- +![](../../assets/VIAtimetable-pics/Frontend.png) +# UI Components +The UI components are grouped into 5 groups as follows: +* AppBar + - CourseSearchBar.vue + - DeliveryMethodSetting.vue + - SwitchSem.vue +* FloatingBtns + - AboutBtn.vue + - ExportBtn.vue + - HelpDail.vue + - TutorialBtn.vue +* Popup + - CourseSectionPicker.vue + - NoTimetablePopup.vue + - OverwriteLockedSectionPopup.vue + - Tutorial.vue +* SidePanel + - SelectedCourseCard.vue + - SelectedCoursesPanel.vue + - SideBar.vue +* Timetable + - HourSwitch.vue + - Timetable.vue + - TimetableCourseCard.vue + - TimetableEvent.vue + - WeekdaySwitch.vue + +## AppBar + +## Popup +## SidePanel +## Timetable diff --git a/via-timetable/state-management/README.md b/via-timetable/state-management/README.md new file mode 100644 index 0000000..583780c --- /dev/null +++ b/via-timetable/state-management/README.md @@ -0,0 +1,111 @@ +--- +sidebar: auto +--- + +# State Management + +The state management is a crucial part for any web-development, as it involves the control of different web state when interact. A badly managed web state can lead development more difficult as the complication increases, a good one is the opposite. Luckily we are able to use a native tool from the framework VUE. + +## VUEX + +Vuex is a state management pattern + library for Vue.js applications. It serves as a centralized store for all the components in an application, with rules ensuring that the state can only be mutated in a predictable fashion. It also integrates with Vue's official devtools extension to provide advanced features such as zero-config time-travel debugging and state snapshot export / import. + +For more information click [here](https://vuex.vuejs.org/) + +## VUEX in VIAplanner + +VUEX is mainly constructed with one main state with three method to interacted with the main state. +![](../../assets/VIAtimetable-pics/VuexRoadmap.png) + +## Main State + +The main state is the core dependency of VIAplanner, any changes to the main state will directly reflect by VIAplanner. The design pattern of VUEX is similar to the singleton design pattern, where we only keep one copy of the data to ensure the simplicity to maintain the in the change of states. + +### fallLockedHourStatus +The following example is part of the main state. It is used to reflect the locked status for fall semester for the [algorithm](/via-timetable/algorithm/) to check when render. +``` js +type fallLockedHourStatus { + fallLockedHourStatus: !localStorage.fallLockedHourStatus ? { + "8 AM": false, + "9 AM": false, + "10 AM": false, + "11 AM": false, + "12 PM": false, + "1 PM": false, + "2 PM": false, + "3 PM": false, + "4 PM": false, + "5 PM": false, + "6 PM": false, + "7 PM": false, + "8 PM": false, + "9 PM": false, + } : JSON.parse(localStorage.fallLockedHourStatus) +} +``` + +### fallTimetable +Another example is the fallTimetable, it is the used to reflect the state of what courses is in the fall semester. Since UofT students' timetable are all repetitive every week, we can simply use one week to represent the entire semester for any students. Futhermore, committing changes this state will directly affect the what courses will show on the fall semester timetable. + +``` js +type fallTimetable { + fallTimetable: !localStorage.fallTimetable ? { + MONDAY: [], + TUESDAY: [], + WEDNESDAY: [], + THURSDAY: [], + FRIDAY: [], + } : JSON.parse(localStorage.fallTimetable) +} +``` + +## Mutations + +Mutation is a very important part for the change in between states. Mutation is responsible for the final step during the process of changing states, as it mutate the value of the main state. + +### setTimetables +The following example shows how the fall timetable and winter timetable is mutated with the parameter that carries a new fall and winter timetable. + +``` js +type setTimetables(state, payload) { + state.fallTimetable = payload[0]; + state.winterTimetable = payload[1]; +} +``` + +## Actions + +Action is a complement action with mutation when making changes to the main state, it can execute multiple mutations in the same time. Most importantly it allows you to put down logics to judge which mutation to execute + +### saveLockedHourStatus +The following example is a demonstration of a simple action that execute two changes to the main state with a if statement to judge the wanted statement. + +``` js +type saveLockedHourStatus(context) { + + if (context.state.semesterStatus === "F") { + context.state.savedLockedHourStatus = JSON.parse( + JSON.stringify(context.state.fallLockedHourStatus)) + } else { + context.state.savedLockedHourStatus = JSON.parse( + JSON.stringify(context.state.winterLockedHourStatus)) + } + +} +``` + +## Getters + +Getter is a different method compare to mutation and action, it doesn't change any value of the main state, but it obtain specific information from the main state. + +### timetable +Obtain the current timetable based on the current semester. +``` js +type timetable(state) { + if (state.semesterStatus === "F") { + return state.fallTimetable; + } else { + return state.winterTimetable; + } +} +```