129 lines
4.9 KiB
Markdown
129 lines
4.9 KiB
Markdown
# ISMIS Helper
|
|
|
|
A lightweight **[Firefox](https://addons.mozilla.org/)** / **[Chrome](https://chromewebstore.google.com/)**
|
|
extension for the USC ISMIS student portal that:
|
|
|
|
- Auto-fills and auto-submits your login.
|
|
- Auto-accepts the privacy-policy modal.
|
|
- Exports a **Study Load PDF** that matches the official layout — bundled **Segoe UI**
|
|
fonts, the USC logo, the course table, and the units total.
|
|
|
|
One codebase builds for **both browsers** (see [Build](#build)).
|
|
|
|
## Features
|
|
|
|
- **Saved login profiles** (stored in `browser.storage.local`) — only one enabled at
|
|
a time, with a master on/off toggle.
|
|
- **One-click Download PDF** button on the Study Load page.
|
|
- PDF settings in the popup:
|
|
- Truncate long course descriptions to match the official PDF (default on).
|
|
- Show/hide `Year Level`, and set a custom Year Level value.
|
|
- **Bundled Segoe UI fonts** for a 1:1 look with the official document.
|
|
- Builds and packages automatically via Gitea Actions (zips + versioned releases).
|
|
|
|
## Install
|
|
|
|
> Temporary/development install. For distribution, publish the built zips to
|
|
> Firefox AMO and the Chrome Web Store — they are store-ready.
|
|
|
|
### Firefox (load temporary add-on)
|
|
|
|
1. Build the Firefox variant (or download `ismis-helper-firefox.zip` from CI):
|
|
```bash
|
|
node scripts/build.js firefox
|
|
```
|
|
The output is at `dist/ismis-helper-firefox.zip` (unzip it, or use `dist/firefox/`
|
|
directly).
|
|
2. Open `about:debugging` in Firefox.
|
|
3. Click **This Firefox** → **Load Temporary Add-on…**.
|
|
4. Select `dist/firefox/manifest.json`.
|
|
5. Open `https://ismis.usc.edu.ph` and use the extension.
|
|
|
|
### Chrome (load unpacked)
|
|
|
|
1. Build the Chrome variant (or download `ismis-helper-chrome.zip` from CI):
|
|
```bash
|
|
node scripts/build.js chrome
|
|
```
|
|
2. Unzip `dist/ismis-helper-chrome.zip` (or use `dist/chrome/` directly).
|
|
3. Open `chrome://extensions` in Chrome.
|
|
4. Enable **Developer mode** (toggle, top-right).
|
|
5. Click **Load unpacked** and select the unzipped `dist/chrome` folder.
|
|
6. Open `https://ismis.usc.edu.ph` and use the extension.
|
|
|
|
> For a persistent install, package and publish via Firefox AMO / Chrome Web Store
|
|
> with the same built zips.
|
|
|
|
## Distribute to real users
|
|
|
|
### Firefox (self-hosted, temporary)
|
|
|
|
> **Note:** Firefox blocks unsigned extensions for normal installs. The proper
|
|
> fix is to sign the add-on via **addons.mozilla.org (AMO)** and publish it there
|
|
> (or self-host a signed `.xpi`). AMO is currently **under maintenance**, so until
|
|
> it returns, the only way to install the unsigned build is to lower Firefox's
|
|
> signing check on each user's machine. This is a per-user browser setting and is
|
|
> **not** suitable for a broad audience — use it for personal / small-group use.
|
|
|
|
1. Build the Firefox variant (or download `ismis-helper-firefox.zip` from a release):
|
|
```bash
|
|
node scripts/build.js firefox
|
|
```
|
|
2. In Firefox, open `about:config` and accept the warning.
|
|
3. Search for `xpinstall.signatures.required` and set it to **`false`**.
|
|
4. **Restart Firefox** for the change to take effect.
|
|
5. Install the add-on from the release zip: drag `ismis-helper-firefox.zip` into
|
|
Firefox (or File → Open File… and select it).
|
|
|
|
> When AMO is back online, prefer the signed route: publish the same zip to AMO
|
|
> (or sign it with `web-ext sign`) so users install it normally without touching
|
|
> `about:config`.
|
|
|
|
### Chrome (self-hosted)
|
|
|
|
Chrome does **not** require signing for normal installs. Users can install the
|
|
built `ismis-helper-chrome.zip` directly:
|
|
|
|
1. Download `ismis-helper-chrome.zip` from a release and unzip it.
|
|
2. Open `chrome://extensions`, enable **Developer mode**, and click **Load unpacked**.
|
|
3. Select the unzipped folder.
|
|
|
|
> For a store experience, publish the same zip to the Chrome Web Store (one-time
|
|
> $5 developer registration).
|
|
|
|
## Build
|
|
|
|
Requires **Node.js** (the `build.js` script itself is dependency-free; `npm install`
|
|
is only needed to run the tests).
|
|
|
|
```bash
|
|
npm install # dev deps for tests
|
|
npm test # run the test suite
|
|
npm run build # build both -> dist/*.zip
|
|
node scripts/build.js all # build both explicitly
|
|
node scripts/build.js chrome # just chrome
|
|
node scripts/build.js all --version 1.3.0 # versioned zips
|
|
```
|
|
|
|
**CI (Gitea Actions):** on every push, both zips are built, tests run, and the
|
|
zips are uploaded as artifacts. When you push a `v*` tag (e.g. `v1.3.0`), it
|
|
additionally creates a **Gitea Release** with both versioned zips attached.
|
|
|
|
## Settings
|
|
|
|
Open the extension popup to:
|
|
- Manage login profiles (add / edit / enable).
|
|
- Toggle the master on/off switch.
|
|
- Set PDF options: truncate descriptions, show/hide `Year Level`, custom Year Level.
|
|
|
|
## Data & privacy
|
|
|
|
- Auto-login stores your portal credentials **in plaintext** on your own device.
|
|
- This is a personal-use helper for the university portal; use it only with your
|
|
own account.
|
|
|
|
## Development
|
|
|
|
See [`AGENTS.md`](AGENTS.md) for the repository layout, build model, and coding
|
|
conventions for this project.
|