324 lines
9.7 KiB
Markdown
324 lines
9.7 KiB
Markdown
# Certificate Module
|
|
|
|
A comprehensive certificate builder system for the Mentor LMS platform that allows admins to create, manage, and activate custom certificate templates for course completion.
|
|
|
|
## Features
|
|
|
|
- **Visual Certificate Builder**: Create custom certificate templates with live preview
|
|
- **Full Customization**: Customize colors, fonts, text, and logos
|
|
- **Template Management**: Create, edit, delete, and activate certificate templates
|
|
- **One Active Template**: Only one template can be active at a time for consistency
|
|
- **Student Downloads**: Students can download certificates in PNG or PDF format
|
|
- **Dynamic Data**: Certificates automatically populate with student name, course name, and completion date
|
|
|
|
## Architecture
|
|
|
|
### Backend (Laravel)
|
|
|
|
#### Database Schema
|
|
|
|
- **Table**: `certificate_templates`
|
|
- `id` - Primary key
|
|
- `name` - Template name for admin reference
|
|
- `logo_path` - Path to uploaded logo (nullable)
|
|
- `template_data` - JSON field containing all customization data
|
|
- `is_active` - Boolean flag (only one can be true at a time)
|
|
- `created_at`, `updated_at` - Timestamps
|
|
|
|
#### Models
|
|
|
|
- **CertificateTemplate** (`Modules/Certificate/app/Models/CertificateTemplate.php`)
|
|
- Handles template CRUD operations
|
|
- Automatically ensures only one template is active
|
|
- Casts `template_data` to array for easy access
|
|
|
|
#### Controllers
|
|
|
|
- **CertificateTemplateController** (`Modules/Certificate/app/Http/Controllers/CertificateTemplateController.php`)
|
|
- `index()` - List all templates for admin
|
|
- `store()` - Create new template
|
|
- `update()` - Update existing template
|
|
- `activate()` - Set a template as active
|
|
- `destroy()` - Delete template (including logo file)
|
|
|
|
- **CertificateController** (`Modules/Certificate/app/Http/Controllers/CertificateController.php`)
|
|
- `show()` - Display certificate download page with active template
|
|
|
|
#### Routes
|
|
|
|
Admin routes (prefix: `/admin`):
|
|
|
|
- `GET /certificate-templates` - List all templates
|
|
- `POST /certificate-templates` - Create template
|
|
- `PUT /certificate-templates/{id}` - Update template
|
|
- `DELETE /certificate-templates/{id}` - Delete template
|
|
- `POST /certificate-templates/{id}/activate` - Activate template
|
|
|
|
Student routes:
|
|
|
|
- `GET /certificates/{courseId}` - View and download certificate
|
|
|
|
### Frontend (React + TypeScript)
|
|
|
|
#### Admin Pages
|
|
|
|
- **Certificate Index** (`resources/js/pages/dashboard/certificate/index.tsx`)
|
|
- Dashboard view showing all certificate templates
|
|
- Grid layout with template cards
|
|
- Quick preview, edit, activate, and delete actions
|
|
- Empty state with call-to-action
|
|
|
|
- **Certificate Builder Form** (`resources/js/pages/dashboard/certificate/partials/certificate-builder-form.tsx`)
|
|
- Comprehensive form for creating/editing templates
|
|
- Real-time preview while editing
|
|
- Sections:
|
|
- Basic Information (name, active status)
|
|
- Logo & Branding (upload logo)
|
|
- Colors (primary, secondary, background, border)
|
|
- Typography (font family selection)
|
|
- Certificate Text (title, description, completion text, footer)
|
|
|
|
- **Certificate Preview** (`resources/js/pages/dashboard/certificate/partials/certificate-preview.tsx`)
|
|
- Reusable preview component
|
|
- Shows how certificate will look with sample data
|
|
- Used in both builder and preview modal
|
|
|
|
#### Student Components
|
|
|
|
- **Dynamic Certificate** (`resources/js/components/dynamic-certificate.tsx`)
|
|
- Displays certificate using active template
|
|
- Download options (PNG/PDF)
|
|
- Canvas-based rendering for high-quality downloads
|
|
- Automatically populates with student data
|
|
|
|
#### Types
|
|
|
|
- **Certificate Types** (`resources/js/types/certificate.d.ts`)
|
|
- TypeScript interfaces for type safety
|
|
- Includes CertificateTemplate, CertificateTemplateData, and page props
|
|
|
|
## Template Data Structure
|
|
|
|
The `template_data` JSON field contains:
|
|
|
|
```json
|
|
{
|
|
"primaryColor": "#3730a3",
|
|
"secondaryColor": "#4b5563",
|
|
"backgroundColor": "#dbeafe",
|
|
"borderColor": "#f59e0b",
|
|
"titleText": "Certificate of Completion",
|
|
"descriptionText": "This certificate is proudly presented to",
|
|
"completionText": "for successfully completing the course",
|
|
"footerText": "Authorized Certificate",
|
|
"fontFamily": "serif"
|
|
}
|
|
```
|
|
|
|
## Installation & Setup
|
|
|
|
### 1. Run Migration
|
|
|
|
```bash
|
|
php artisan migrate
|
|
```
|
|
|
|
### 2. Ensure Storage Link
|
|
|
|
```bash
|
|
php artisan storage:link
|
|
```
|
|
|
|
### 3. File Permissions
|
|
|
|
Ensure the `storage/app/public/certificates/logos/` directory is writable.
|
|
|
|
### 4. Frontend Dependencies
|
|
|
|
All required packages should already be installed:
|
|
|
|
- `jspdf` - PDF generation
|
|
- `date-fns` - Date formatting
|
|
- Shadcn/UI components
|
|
|
|
## Usage
|
|
|
|
### Admin: Creating a Certificate Template
|
|
|
|
1. Navigate to **Admin Dashboard** → **Certificate Templates**
|
|
2. Click **"Create Template"**
|
|
3. Fill in the form:
|
|
- **Template Name**: Give it a descriptive name
|
|
- **Logo**: Upload your institution/course logo (optional)
|
|
- **Colors**: Choose your brand colors using color pickers
|
|
- **Typography**: Select font style (serif, sans-serif, etc.)
|
|
- **Text Content**: Customize all certificate text
|
|
4. Preview updates in real-time on the right side
|
|
5. Toggle **"Set as Active Template"** to make it the active certificate
|
|
6. Click **"Create Template"** to save
|
|
|
|
### Admin: Managing Templates
|
|
|
|
- **View All**: See all templates in a grid layout
|
|
- **Preview**: Click on the mini-preview to see full-size preview
|
|
- **Edit**: Click "Edit" button to modify template
|
|
- **Activate**: Click "Activate" to set as the active template (deactivates others)
|
|
- **Delete**: Click trash icon to delete template
|
|
|
|
### Student: Downloading Certificate
|
|
|
|
1. Complete a course
|
|
2. Navigate to the course certificate page
|
|
3. Choose download format (PNG or PDF)
|
|
4. Click "Download" button
|
|
5. Certificate is generated with your name, course name, and completion date
|
|
|
|
## Customization Options
|
|
|
|
### Colors
|
|
|
|
- **Primary Color**: Main headings and student name
|
|
- **Secondary Color**: Body text and descriptions
|
|
- **Background Color**: Certificate background
|
|
- **Border Color**: Decorative borders and lines
|
|
|
|
### Typography
|
|
|
|
- **Serif**: Classic, formal look
|
|
- **Sans Serif**: Modern, clean look
|
|
- **Monospace**: Technical, code-style look
|
|
- **Cursive**: Elegant, handwritten style
|
|
|
|
### Text Fields
|
|
|
|
All text fields support custom content including:
|
|
|
|
- Title (default: "Certificate of Completion")
|
|
- Description (default: "This certificate is proudly presented to")
|
|
- Completion text (default: "for successfully completing the course")
|
|
- Footer (default: "Authorized Certificate")
|
|
|
|
## API Endpoints
|
|
|
|
### Admin Endpoints
|
|
|
|
**List Templates**
|
|
|
|
```
|
|
GET /admin/certificate-templates
|
|
Response: { templates: CertificateTemplate[] }
|
|
```
|
|
|
|
**Create Template**
|
|
|
|
```
|
|
POST /admin/certificate-templates
|
|
Body: {
|
|
name: string,
|
|
logo: File (optional),
|
|
template_data: object,
|
|
is_active: boolean
|
|
}
|
|
```
|
|
|
|
**Update Template**
|
|
|
|
```
|
|
PUT /admin/certificate-templates/{id}
|
|
Body: Same as create
|
|
```
|
|
|
|
**Activate Template**
|
|
|
|
```
|
|
POST /admin/certificate-templates/{id}/activate
|
|
```
|
|
|
|
**Delete Template**
|
|
|
|
```
|
|
DELETE /admin/certificate-templates/{id}
|
|
```
|
|
|
|
### Student Endpoints
|
|
|
|
**View Certificate**
|
|
|
|
```
|
|
GET /certificates/{courseId}
|
|
Response: { courseId, certificateTemplate, student, course, completionDate }
|
|
```
|
|
|
|
## Technical Notes
|
|
|
|
### Image Handling
|
|
|
|
- Logos are stored in `storage/app/public/certificates/logos/`
|
|
- Supported formats: JPEG, PNG, JPG, SVG
|
|
- Maximum file size: 2MB
|
|
- Files are automatically deleted when template is deleted
|
|
|
|
### Active Template Logic
|
|
|
|
- Only one template can be active at a time
|
|
- Activating a template automatically deactivates all others
|
|
- Handled in the model's `boot()` method using an event listener
|
|
- If no active template exists, default template data is used
|
|
|
|
### Canvas Rendering
|
|
|
|
- Certificates use HTML5 Canvas for download generation
|
|
- Ensures high-quality, resolution-independent output
|
|
- Supports both PNG and PDF formats
|
|
- Font rendering uses system fonts for consistency
|
|
|
|
## Future Enhancements
|
|
|
|
Potential features for future versions:
|
|
|
|
- Multiple layout templates (portrait, landscape, different designs)
|
|
- Signature field support
|
|
- QR code for certificate verification
|
|
- Email certificate directly to students
|
|
- Certificate expiration dates
|
|
- Multi-language support for certificate text
|
|
- Custom field placeholders (e.g., instructor name, course duration)
|
|
- Certificate analytics and download tracking
|
|
|
|
## Troubleshooting
|
|
|
|
### Logo not displaying
|
|
|
|
- Ensure `php artisan storage:link` has been run
|
|
- Check file permissions on storage directory
|
|
- Verify logo file was uploaded successfully
|
|
|
|
### Template not saving
|
|
|
|
- Check browser console for errors
|
|
- Verify CSRF token is valid
|
|
- Ensure all required fields are filled
|
|
|
|
### Download not working
|
|
|
|
- Check browser console for errors
|
|
- Ensure jsPDF is installed
|
|
- Try different download format (PNG vs PDF)
|
|
|
|
## Support
|
|
|
|
For issues or questions, please contact the development team or create an issue in the project repository.
|
|
|
|
## Structure
|
|
|
|
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
|
|
│ Admin │────────>│ Template CRUD │────────>│ Database │
|
|
│ Dashboard │ │ Controller │ │ (JSON) │
|
|
└─────────────┘ └──────────────────┘ └─────────────┘
|
|
│
|
|
v
|
|
┌─────────────┐ ┌──────────────────┐ ┌─────────────┐
|
|
│ Student │────────>│ Certificate │────────>│ Active │
|
|
│ Download │ │ Controller │ │ Template │
|
|
└─────────────┘ └──────────────────┘ └─────────────┘
|