lms/Modules/Certificate

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:

{
   "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

php artisan migrate

2. Ensure Storage Link

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 │ └─────────────┘ └──────────────────┘ └─────────────┘