128 lines
5.1 KiB
Markdown
128 lines
5.1 KiB
Markdown
# ISMIS Helper — Firefox Extension Design
|
|
|
|
**Date:** 2026-08-18
|
|
**Status:** Approved
|
|
**Target site:** `https://ismis.usc.edu.ph` (USC ISMIS student portal)
|
|
|
|
## Overview
|
|
|
|
A personal Firefox extension (Manifest V3, no build step) that improves the USC ISMIS
|
|
student portal experience. It provides three features:
|
|
|
|
1. **Auto-login** — auto-fill and auto-submit the login form from a saved profile.
|
|
2. **Auto-accept Privacy Policy** — dismiss the recurring privacy-policy modal.
|
|
3. **Study Load PDF** — generate a PDF of the student's study load, replicating the
|
|
official ISMIS document, including course descriptions looked up from the
|
|
Offered Courses endpoint.
|
|
|
|
A single **master toggle** disables all extension behavior on the portal.
|
|
|
|
## Architecture
|
|
|
|
Single MV3 extension, plain JavaScript, no bundler.
|
|
|
|
```
|
|
ismis-helper/
|
|
├── manifest.json # MV3 manifest, permissions, content script, popup
|
|
├── background.js # service worker: message routing + PDF generation
|
|
├── content.js # runs on ismis.usc.edu.ph: auto-login, privacy, scraping
|
|
├── popup.html # popup UI
|
|
├── popup.js # popup logic
|
|
├── popup.css # popup styles
|
|
├── libs/pdf-lib.min.js # vendored pdf-lib library
|
|
└── icons/ # extension icons (16, 32, 48, 128)
|
|
```
|
|
|
|
### Permissions (manifest.json)
|
|
- `storage` — persist profiles and the master toggle.
|
|
- `downloads` — save the generated Study Load PDF.
|
|
- `activeTab` — access the current tab for scraping.
|
|
- Content script matches `https://ismis.usc.edu.ph/*`.
|
|
|
|
## Component 1 — Auto-login
|
|
|
|
- Content script runs on `https://ismis.usc.edu.ph/Account/Login`.
|
|
- Reads the active (first enabled) profile from `browser.storage.local`.
|
|
- Locates the username and password input fields (by common `name`/`id` values such
|
|
as `UserName`, `Password`, `username`, `password`).
|
|
- Fills both fields, then submits the form (auto-submit).
|
|
- If no profile is enabled, or the master toggle is off, does nothing.
|
|
|
|
## Component 2 — Auto-accept Privacy Policy
|
|
|
|
- On any portal page, if the privacy modal `#myModal` is present and visible:
|
|
- Check the `#Confirmation` checkbox ("I have read and understood the Privacy
|
|
Policy Statement").
|
|
- Click the `#Submit` button (Continue), which is disabled until the checkbox is
|
|
checked.
|
|
- Gated by the master toggle.
|
|
|
|
## Component 3 — Profiles
|
|
|
|
- Stored in `browser.storage.local` under key `profiles` as an array of:
|
|
`{ id, name, username, password, enabled }`.
|
|
- Popup provides add, edit, delete, and enable/disable per profile.
|
|
- The first profile with `enabled === true` is used for auto-login.
|
|
- Master toggle stored under key `enabled` (boolean).
|
|
|
|
## Component 4 — Study Load PDF
|
|
|
|
### Scrape
|
|
- On the Study Load page, parse the course table with columns:
|
|
**Group #, Course Code, Schedule, Faculty, Units, Status**.
|
|
- Read the total-units footer (e.g. `12.00 Units / Total Units: 18.00`).
|
|
- Header fields (student ID, name, program, year level, semester, date enrolled)
|
|
are scraped when present on the page; otherwise they are entered manually in the
|
|
popup before generating the PDF.
|
|
|
|
### Description lookup
|
|
- For each unique course code, POST to
|
|
`https://ismis.usc.edu.ph/CourseSchedule/CourseScheduleOffered` with form data:
|
|
- `Courses=<course code>`
|
|
- `AcademicPeriod=<selected value>`
|
|
- `AcademicYear=<selected value>`
|
|
- `__RequestVerificationToken=<token from page>`
|
|
- plus the `AjaxFormVM.*` fields observed in the HAR capture.
|
|
- Parse the returned HTML table to extract the **Course Description** for the course.
|
|
- If lookup fails for a course, leave the description blank and continue.
|
|
|
|
### Manual fallback
|
|
- If scraping finds no table, the popup shows a manual entry form for the same fields
|
|
(including optional course descriptions).
|
|
|
|
### PDF generation
|
|
- `background.js` uses **pdf-lib** to build the PDF replicating the official layout:
|
|
- Header block: semester, "STUDENT'S STUDY LOAD", date range, date enrolled,
|
|
student ID, name, program, year level.
|
|
- Course table: Course, Course Description, Units, Teacher, Group, Note
|
|
(status: REGULAR/PARALLEL/DISSOLVED), Schedule.
|
|
- Footer: total units, printed-by line.
|
|
- Downloads the PDF via the `downloads` API.
|
|
|
|
## Data flow
|
|
|
|
```
|
|
popup ──message──▶ background ──message──▶ content (scrape + description lookup)
|
|
▲ │
|
|
└────────────── data back ◀────────────────────┘
|
|
│
|
|
▼
|
|
pdf-lib → download
|
|
```
|
|
|
|
## Error handling
|
|
|
|
- Master toggle off → no extension behavior on the portal.
|
|
- No enabled profile → no auto-login.
|
|
- Description lookup fails for a course → blank description, PDF still generated.
|
|
- Scrape fails entirely → manual entry form in the popup.
|
|
- Login fields not found → log a warning, no crash.
|
|
|
|
## Testing
|
|
|
|
- Load via `about:debugging` → "Load Temporary Add-on".
|
|
- Verify auto-login on the login page.
|
|
- Verify privacy modal auto-accept.
|
|
- Verify profile add/edit/delete/toggle and master toggle.
|
|
- Verify Study Load PDF generation: scrape, description lookup, manual fallback.
|