# Practical Guidelines — setup and use

## Install
1. Back up the application and database. Deploy this slps folder while preserving your production settings and uploaded data.
2. In phpMyAdmin, select the existing SLPS database and import database/migrations/20261015_practical_guidelines.sql. It adds two tables and can be run again safely. For a new installation, the main database/slps_schema.sql already includes these tables.
3. Ensure the PHP process can write to SLPS_PRIVATE_STORAGE (or the existing private storage location). For 20 MB attachments, configure upload_max_filesize=20M and post_max_size=25M or greater. PHP mysqli, fileinfo and ctype must be enabled, as used by this application.
4. Refresh the browser with Ctrl+F5. Open Practical Guidelines from the sidebar.

No editor API key or external CDN is required. Quill 2.0.3 is bundled locally under shared/vendor/quill with its license. The current sharp-corner green/gold/charcoal design is retained.

## Admin and HOD workflow
- Admins can select departments and manage guidelines for any active course. HODs can manage courses in their assigned department.
- Existing active database courses appear automatically. Use Add course (Bootstrap modal) for a new course code and title.
- Use Course library beside Refresh to search/filter the course popup, then click a course. The popup closes and its editor fills the content width. Formatting includes six heading levels, font families, text sizes, bold/italic/underline/strike, subscript/superscript, colours/highlights, alignment, indentation, numbered/bullet/check lists, right-to-left text, quotations, code blocks, links and tables.
- Insert code opens a dialog for pasting or typing code with tabs and line breaks preserved. The code is rendered as a monospace block and never executed.
- Edit published version reopens the content and resources currently visible to students, allowing changes to be saved as a draft or republished. Existing draft revisions remain protected against conflicting saves.
- Table inserts a 3×3 table. Place the cursor in a table and choose Table actions to insert/remove rows or columns or remove the table.
- Use the image tool, paste an image or drop an image into the editor to upload a JPG/PNG/WebP image (up to 5 MB). External pasted image HTML is stripped; use uploaded images.
- Use Attachment for PDF, DOCX, XLSX, PPTX or TXT files (up to 20 MB). PDFs open in the browser; other resources download. Remove detaches a resource from the current draft.
- Save draft keeps changes private to editors. Publish to students saves the current content and resources as the student-visible version. A new draft does not overwrite the published version until published.
- Student preview shows the current editor content in a read-only layout. Unsaved changes trigger a warning when switching courses, department filters or leaving. Conflicting saves are rejected so one editor cannot silently overwrite another.

## Student and staff view
Students see only active courses in their assigned department. Clicking a course opens its published notes, embedded images and resources; there is no student editor or upload control. Unpublished courses display a clear message. Staff have read-only published access in their assigned department.

Old file/guide navigation entries now open the new course workspace, with duplicate navigation entries removed. Existing file records and old guide records are retained; they are not automatically converted into course notes.

## Validation
Tested with PHP 8.3 and an isolated MariaDB 10.11 database using the supplied schema and migration. Live checks covered department isolation, admin/HOD authoring, student/staff read-only access, CSRF rejection, unsafe-format rejection, image/PDF uploads, private draft assets, publication, student attachment access and conflicting revisions.

Chromium checks covered actual HOD editing/saving through the PHP endpoints, persisted table formatting, legacy URLs, one Guidelines navigation entry, student published content, hidden drafts, and desktop/mobile layouts in light/dark themes. Additional UI checks covered unsaved changes, table insertion, attachments, preview and conflict preservation.
