- Use academic calendar details

README.md

@@ -2,6 +2,8 @@
 
 This is a **Chrome Browser Extension** that allows exporting a VIT Timetable as an `iCalendar` (`.ics`) file.
 
+All the events are created as per the Academic Calendar for a given Semester, which includes extra instructional days (with specified day order), holidays and exam dates.
+
 The exported `.ics` file can be imported into Google Calendar or any other Calendar application.
 
 - [Installation](#installation)
@@ -23,15 +25,28 @@ You should see something like this after the above steps:
 
 ## Usage
 
-- Login to VTOP and navigate to the Timetable page
+- Login to VTOP and first navigate to the Academics Calendar page
+  - Under `Academics > Academics Calendar`
+- With the plugin installed, you should see something like this (with `Save`, `View saved` and `Clear saved` buttons):
+
+> ![VIT Timetable Export Plugin - Academics Calendar view](images/academics-calendar-view-1.png)
+
+- Select the relevant semester and the correct Class Group
+  - The `Academics > Time table` page shows the Class Group in the 2nd column of the first table
+- Select **each** of the displayed months to display the calendar for that month and then click on the `Save` button for **each** one of them
+- Once **all** the months are selected and saved, clicking on the `View saved` button should show somthing like this:
+  - In the example below, academic calendar details for the months of 'July, August, September, October and November 2024' for the 'Fall Semester 2024-25' and 'General Freshers' class group are saved
+
+> ![VIT Timetable Export Plugin - Academics Calendar view](images/academics-calendar-view-2.png)
+
+- Now, navigate to the Timetable page
   - Under `Academics > Time table`
 - With the plugin installed, you should see something like this (with an `Export Calendar` button):
 
 > ![VIT Timetable Export Plugin - Export Button](images/export-button.png)
 
-- Select the relevant semester and click on the `Export Calendar` button
-  - Select a different starting date if needed - events will start from the Monday of that week
-  - By default, recurring events for 18 weeks are created. This can be changed in the input box.
+- Select the same semester for which academic calendar details are saved above and click on the `Export Calendar` button
+  - If you haven't saved the academic calendar details as mentioned previously, you will be alerted with error messages.  Please follow the instructions and try again
 - The `.ics` file will be exported as shown below:
   - The filename will be `VIT-<semester-info>.ics`
 
@@ -75,6 +90,8 @@ To import into Google Calendar
 
 ## How it works
 
+> v1.1 and above uses the academic calendar details for a given semester to create all the events, including additional instructional days, holidays and exams.  All the details mentioned below still apply, with a few more changes to observe for the `Academics Calendar` page, parsing the calendars on that page and saving them to `localStorage` to be later used in the `Time table` page
+
 All of VTOP's content is dynamically generated.  There is a single URL `https://vtop.vit.ac.in/vtop/content` under which all content resides and the browser does not navigate to different pages for different sections.  The code to export the Timetable data needs to run on the `Time Table` page.  There are a few ways to achieve this, all of which require code to be injected as [Content Scripts](https://developer.chrome.com/docs/extensions/develop/concepts/content-scripts#capabilities) and run:
 
 - Register a [context menu](https://developer.chrome.com/docs/extensions/reference/api/contextMenus) item like `Export Timetable` (right-click option) for the main content page, which when clicked in the `Time Table` page, injects and runs the export code
@@ -84,10 +101,10 @@ All of VTOP's content is dynamically generated.  There is a single URL `https://
   - The [MutationObserver](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver) API provides the ability to watch for changes being made to the DOM tree
   - `b5-pagewrapper` is the div under which most of the core page content resides (`b5pwO` is the observer object and `b5pwCb` is the callback when changes are observed)
   - This div doesn't show up right after login, which is why the `page_outline` div needs to be observed till the `b5-pagewrapper` is found (`poO` is the observer object and `poCb` is the callback).  This observer is stopped as soon as `b5-pagewrapper` is found
-  - The `studentTimeTable` form in `b5-pagewrapper` indicates that the `Time Table` section is loaded and the HTML to show the export button and the input for the number of recurring weeks (`iHtml`) is injected at the end of the form
+  - The `studentTimeTable` form in `b5-pagewrapper` indicates that the `Time Table` section is loaded and the HTML to show the export button (`iHtml`) is injected at the end of the form
   - The click handler for the export button `exportCalendar` runs the code to parse the tables, generate the ICS text content and export the file
-    - The first table is parsed only for the course ID to name mapping (`parseCourseNames`) so that the full course name is used in the calendar event
-    - The second table provides the start and end times for all the theory and lab slots (first four rows) and the schedule for all the days of the week.  The first column has rows that span two column widths each and hence the column counts are adjusted accordingly depending on the row. `parseTT` parses this table and generates events from the beginning of the week (Monday) when the export is run
-    - The ICS format follows a sample exported from Google Calendar which has recurring weekly events and passes the iCalendar [validator](https://icalendar.org/validator.html) for standalone use or for importing events from it.  The file is exported as `VIT-<semester-info>.ics`
+    - The first table is parsed only for the course ID to course details mapping (`parseCourses`) so that the full course name and other details are used in the calendar event
+    - The second table provides the start and end times for all the theory and lab slots (first four rows) and the schedule for all the days of the week.  The first column has rows that span two column widths each and hence the column counts are adjusted accordingly depending on the row. `parseTT` parses this table and generates events corresponding to each weekday
+    - The ICS format follows a sample exported from Google Calendar and passes the iCalendar [validator](https://icalendar.org/validator.html) for standalone use or for importing events from it.  The file is exported as `VIT-<semester-info>.ics`
 
 > Note: Parsing raw data from HTML tables is always error-prone and is bound to break with any underlying page changes in the future.