Appearance

Module Customization ​

This guide covers advanced module customization including template modifications, frontend and backend customization, and best practices for extending module functionality.

Table of Contents ​

  1. Overview
  2. Module-Specific Customizations
  3. Template Modifications
  4. Frontend Customization
  5. Backend Customization
  6. Best Practices

Overview ​

What Can Be Customized ​

  • ✅ Module templates
  • ✅ Frontend display
  • ✅ Backend functionality
  • ✅ Styling and layout
  • ✅ Module behavior
  • ✅ Integration points

Prerequisites ​

  • Basic coding knowledge
  • Understanding of application structure
  • Access to codebase
  • Development environment

Module-Specific Customizations ​

Understanding Module Structure ​

Module Components ​

Backend:

  • Models
  • Controllers
  • Routes
  • Migrations

Frontend:

  • Vue components
  • Pages
  • Styles

Database:

  • Tables
  • Relationships
  • Indexes

Customization Levels ​

Level 1: Configuration ​

What:

  • Module settings
  • Custom fields
  • Display options

How:

  • Admin panel
  • Settings pages
  • No code changes

Level 2: Template Overrides ​

What:

  • Template modifications
  • CSS changes
  • Layout adjustments

How:

  • Edit template files
  • Add custom CSS
  • Modify components

Level 3: Code Modifications ​

What:

  • Controller changes
  • Model extensions
  • Route modifications

How:

  • Edit source code
  • Add custom code
  • Extend functionality

Template Modifications ​

Admin Templates ​

Location ​

Path: resources/js/Pages/Admin/{Module}/

Files:

  • Index.vue - List view
  • Create.vue - Create form
  • Edit.vue - Edit form
  • Show.vue - Detail view

Modifying Templates ​

What Can Be Changed:

  • Layout: Page structure
  • Forms: Form fields and layout
  • Lists: List display and columns
  • Styling: CSS classes and styles

Best Practices:

  • Keep original as backup
  • Document changes
  • Test thoroughly
  • Use version control

Frontend Templates ​

Location ​

Path: resources/js/Pages/Frontend/

Files:

  • Module-specific pages
  • List views
  • Detail views
  • Components

Customization Options ​

Layout:

  • Change page structure
  • Modify grid layout
  • Adjust spacing

Content:

  • Add custom content
  • Modify display
  • Add sections

Styling:

  • Custom CSS
  • Theme colors
  • Typography

Frontend Customization ​

CSS Customization ​

Custom CSS ​

Location: Design Settings → Custom CSS

What Can Be Done:

  • Override default styles
  • Add custom styles
  • Modify module appearance
  • Responsive adjustments

Example:

css
/* Custom module styling */
.module-list {
    display: grid;
    grid-template-columns: repeat(3, 1fr);
    gap: 20px;
}

.module-card {
    border-radius: 8px;
    box-shadow: 0 2px 10px rgba(0,0,0,0.1);
}

Component Customization ​

Modifying Components ​

Location: resources/js/Components/

What Can Be Changed:

  • Component structure
  • Component behavior
  • Component styling
  • Component props

Best Practices:

  • Extend existing components
  • Don't modify core components
  • Create custom components
  • Document changes

Layout Customization ​

Page Layouts ​

Options:

  • Full width
  • Boxed layout
  • Sidebar layout
  • Custom layout

Implementation:

  • Modify layout components
  • Add custom layouts
  • Use layout settings

Backend Customization ​

Controller Modifications ​

Adding Methods ​

Example:

php
public function customAction(Request $request)
{
    // Custom logic
    return response()->json(['success' => true]);
}

Add Route:

php
Route::post('/custom-action', [Controller::class, 'customAction'])
    ->name('custom-action');

Modifying Methods ​

Best Practices:

  • Keep original logic
  • Add new functionality
  • Don't break existing features
  • Test thoroughly

Model Extensions ​

Adding Methods ​

Example:

php
public function customMethod()
{
    // Custom logic
    return $this->relatedData;
}

Adding Scopes ​

Example:

php
public function scopeActive($query)
{
    return $query->where('status', 'active');
}

Route Modifications ​

Adding Routes ​

Admin Routes:

php
Route::get('/custom', [Controller::class, 'custom'])
    ->name('custom');

Frontend Routes:

php
Route::get('/custom', [Controller::class, 'custom'])
    ->name('custom');

Best Practices ​

Development Workflow ​

  1. Use Development Environment:

    • Test in development first
    • Never modify production directly
    • Use version control

  2. Backup Before Changes:

    • Backup code
    • Backup database
    • Keep backups

  3. Incremental Changes:

    • Make small changes
    • Test after each
    • Build up gradually

Code Organization ​

  1. Keep It Organized:

    • Group related changes
    • Use consistent naming
    • Document code

  2. Don't Modify Core:

    • Extend, don't modify
    • Use hooks/events
    • Create custom files

  3. Version Control:

    • Use Git
    • Commit regularly
    • Write good commit messages

Testing ​

  1. Test Thoroughly:

    • Test all functionality
    • Test edge cases
    • Test on different devices

  2. Test After Updates:

    • Test after core updates
    • Verify compatibility
    • Fix any issues

Documentation ​

  1. Document Changes:

    • Document what changed
    • Note why
    • Update guides

  2. Keep Notes:

    • Keep change log
    • Note customizations
    • Document dependencies

Troubleshooting ​

Customizations Not Working ​

Solutions:

  1. Clear cache
  2. Check file paths
  3. Verify code syntax
  4. Check permissions
  5. Review error logs

Conflicts with Updates ​

Solutions:

  1. Review update notes
  2. Check for conflicts
  3. Update customizations
  4. Test thoroughly
  5. Get help if needed

Performance Issues ​

Solutions:

  1. Review custom code
  2. Optimize queries
  3. Check for N+1 problems
  4. Use caching
  5. Profile code

Last Updated: [Date will be updated during final review]

Released under the MIT License.

Copyright © 2024 OmniSuite CMS