Building Master-Detail Relationships in CRUDBooster: A Complete Guide

Home / Articles / Building Master-Detail Relationships in CRUDBooster: A Complete Guide
Building Master-Detail Relationships in CRUDBooster: A Complete Guide
By Ferry Oct 31, 2025 79 views

Ever found yourself needing to manage related data in your admin panel? Like categories and their subcategories, or customers and their orders? If you're using CRUDBooster, you're in luck! The Master-Detail (Sub Module) feature makes this incredibly straightforward.

Let me walk you through everything you need to know about implementing master-detail relationships in CRUDBooster, from the basics to real-world examples.

What Are Master-Detail Relationships?

 

Think of master-detail relationships as parent-child data structures. The master (parent) contains the main record, while the detail (child) contains related records that belong to that master. Common examples include:

  • Categories → Subcategories

  • Customers → Orders

  • Projects → Tasks

  • Invoices → Invoice Items

In traditional admin panels, you'd typically navigate between separate pages to manage these relationships. With CRUDBooster's Sub Module feature, you can manage both the master and detail records from a single interface - pretty neat, right?

 

Prerequisites

Before diving in, make sure you have:

  1. CRUDBooster 7.x installed and running

  2. Two related database tables with a foreign key relationship

  3. Basic understanding of CRUDBooster module creation

  4. Generated modules for both your master and detail tables

For this tutorial, I'll use a practical example: managing categories and their subcategories.

Setting Up the Database Structure

Let's start with a simple database structure. You'll need two tables with a foreign key relationship:

-- Categories table (Master)
CREATE TABLE categories (
    id INT PRIMARY KEY AUTO_INCREMENT,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

-- Subcategories table (Detail)
CREATE TABLE subcategories (
    id INT PRIMARY KEY AUTO_INCREMENT,
    category_id INT NOT NULL,
    name VARCHAR(255) NOT NULL,
    description TEXT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FOREIGN KEY (category_id) REFERENCES categories(id)
);

The key here is the category_id foreign key in the subcategories table - this links each subcategory to its parent category.

Step 1: Generate Your Modules

First, you'll need to create modules for both tables. You can do this through the CRUDBooster admin panel or via command line:

# Generate category module
php artisan cb:crud categories --name=Categories

# Generate subcategory module
php artisan cb:crud subcategories --name=Subcategories

This creates all the necessary files for both modules. At this point, you have two separate modules that work independently.

Step 2: Configure the Master Module

Now comes the magic! Navigate to your master module's form component. In our case, that's the CategoryForm component located at app/Cb/Modules/Categories/Livewire/CategoriesForm.php.

Here's how to integrate the sub-module:

<?php

namespace App\Cb\Modules\Categories\Livewire;

use App\Cb\Modules\Categories\Services\CategoriesService;
use App\Cb\Modules\Categories\Models\Categories as CategoriesModel;
use App\Cb\Modules\Subcategories\Livewire\Subcategories;
use CrudBooster\Livewire\BaseFormComponent;
use CrudBooster\Livewire\FormBuilder\Form;
use CrudBooster\Components\MasterDetail\SubModule;

class CategoriesForm extends BaseFormComponent
{
    public $pageTitle = "Categories";
    protected $modelService = CategoriesService::class;
    protected $modelName = CategoriesModel::class;

    public function init()
    {
        // Configure your form fields as usual
        $this->makeForm([
            Form::add(label: "Name", key: "name", type: "text", validation: "required"),
            Form::add(label: "Description", key: "description", type: "textarea"),
        ]);

        // Here's where the magic happens!
        $this->addSubModule([
            SubModule::create(Subcategories::class)->foreignKey('category_id'),
        ]);
    }
}

Let me break down what's happening here:

  • SubModule::create(): This creates a new sub-module instance

  • Subcategories::class: This refers to the browse component (not the form component!) of your detail module

  • foreignKey('category_id'): This specifies which field links the detail records to the master record

Step 3: Handle Menu Visibility (Optional)

Since your subcategories are now accessible through the categories module, you might want to hide the standalone subcategories menu. You can do this in the CRUDBooster admin panel under Menu Management, or simply leave it visible if you want both access methods.

Real-World Use Cases

Let me show you some practical examples of where master-detail relationships shine:

E-commerce Product Management

// In ProductsForm.php
$this->addSubModule([
    SubModule::create(ProductVariants::class)->foreignKey('product_id'),
    SubModule::create(ProductImages::class)->foreignKey('product_id'),
]);

This allows you to manage product variants and images directly from the product editing page.

Customer Relationship Management

// In CustomersForm.php
$this->addSubModule([
    SubModule::create(CustomerOrders::class)->foreignKey('customer_id'),
    SubModule::create(CustomerNotes::class)->foreignKey('customer_id'),
]);

Perfect for viewing all customer orders and notes in one place.

Project Management

// In ProjectsForm.php
$this->addSubModule([
    SubModule::create(ProjectTasks::class)->foreignKey('project_id'),
    SubModule::create(ProjectFiles::class)->foreignKey('project_id'),
]);

Keep all project-related data organized and easily accessible.

Advanced Configuration

Multiple Sub-Modules

You can add multiple sub-modules to a single master record:

$this->addSubModule([
    SubModule::create(Subcategories::class)->foreignKey('category_id'),
    SubModule::create(CategoryAttributes::class)->foreignKey('category_id'),
    SubModule::create(CategoryImages::class)->foreignKey('category_id'),
]);

Custom Foreign Key Names

If your foreign key doesn't follow the standard naming convention:

$this->addSubModule([
    SubModule::create(Subcategories::class)->foreignKey('parent_category_id'),
]);

What You Get Out of the Box

When you implement master-detail relationships, CRUDBooster automatically provides:

  1. Integrated Interface: Sub-modules appear as tabs or sections within the master record's detail page

  2. Automatic Filtering: Detail records are automatically filtered to show only those belonging to the current master record

  3. Context Awareness: New detail records automatically inherit the master record's ID

  4. Seamless Navigation: Users can manage related data without leaving the master record context

Best Practices

Here are some tips to get the most out of master-detail relationships:

1. Plan Your Data Structure

Before implementing, think about which relationships truly benefit from this approach. Not every related table needs to be a sub-module.

2. Consider User Experience

Ask yourself: "Would users expect to manage this data together?" If yes, it's a good candidate for master-detail.

3. Performance Considerations

While convenient, loading multiple sub-modules can impact performance. Use this feature judiciously for high-traffic applications.

4. Maintain Data Integrity

Ensure your foreign key constraints are properly set up in the database to prevent orphaned records.

Troubleshooting Common Issues

Sub-Module Not Appearing

  • Double-check that you're referencing the browse component class, not the form component

  • Verify the foreign key name matches your database column

  • Ensure the sub-module class exists and is properly imported

Foreign Key Errors

  • Confirm your database foreign key constraints are set up correctly

  • Check that the foreign key field name matches exactly

Permission Issues

  • Make sure users have appropriate permissions for both master and detail modules

The Result

Once implemented, your master-detail interface will look clean and professional. Users can view the master record details at the top, with related detail records displayed in an organized section below. It's intuitive, efficient, and significantly improves the user experience.

The beauty of CRUDBooster's master-detail feature lies in its simplicity. With just a few lines of code, you transform separate, disconnected modules into a cohesive, user-friendly interface that makes data management a breeze.

Ready to Build Better Admin Panels?

Master-detail relationships are just one of the many powerful features that make CRUDBooster a game-changer for rapid application development. Whether you're building a simple admin panel or a complex business application, CRUDBooster provides the tools you need to create professional, feature-rich interfaces in record time.

Ready to experience the power of CRUDBooster for yourself? Download CRUDBooster today and start building better admin panels in minutes, not hours. Your future self (and your users) will thank you!

← Back to Articles