Filament Quick Create Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require awcodes/filament-quick-create
   

   Ensure you have a custom Filament theme and add the plugin's views to your theme CSS:

   @source '../../../../vendor/awcodes/filament-quick-create/resources/**/*.blade.php';
   

2. Register the Plugin: Add the plugin to your Panel configuration in app/Providers/Filament/AdminPanelProvider.php:

   public function panel(Panel $panel): Panel
   {
       return $panel
           ->plugins([
               QuickCreatePlugin::make(),
           ]);
   }
   

3. First Use Case: Navigate to your Filament admin panel. A new dropdown button (default: "+ New") will appear in the header, listing all resources where the current user has create permissions. Clicking an item opens the resource's create form (modal or redirect, depending on the resource).

Implementation Patterns

Core Workflow

1. Resource Filtering:

   • Exclude Resources: Hide specific resources from the dropdown:

     QuickCreatePlugin::make()->excludes([UserResource::class])
     

   • Include Resources: Show only specific resources:

     QuickCreatePlugin::make()->includes([PostResource::class, ProductResource::class])
     

   • Note: Use either excludes or includes, not both.

2. Sorting Options:

   • Default: Sorts by resource label (descending).
   • Disable sorting:

     QuickCreatePlugin::make()->sort(false)
     

   • Sort by navigation order:

     QuickCreatePlugin::make()->sortBy('navigation')
     

3. UI Customization:

   • Button Appearance:
     • Rounded (default) or square:

       QuickCreatePlugin::make()->rounded(false)
       

     • Custom label:

       QuickCreatePlugin::make()->label('Create New')
       

     • Hide icons:

       QuickCreatePlugin::make()->hiddenIcons()
       

   • Modal vs. Redirect:
     • Force all resources to use modals:

       QuickCreatePlugin::make()->alwaysShowModal()
       

     • Use slide-over for modals (default for "simple" resources):

       QuickCreatePlugin::make()->slideOver()
       

4. Conditional Visibility: Hide the plugin dynamically (e.g., during onboarding):

   QuickCreatePlugin::make()->hidden(fn() => Filament::getTenant()->requiresOnboarding())
   

5. Keyboard Shortcuts: Add global shortcuts to trigger the dropdown:

   QuickCreatePlugin::make()->keyBindings(['command+shift+a', 'ctrl+shift+a'])
   

6. Custom Render Hook: Change where the plugin renders (e.g., in the sidebar):

   QuickCreatePlugin::make()->renderUsingHook(PanelsRenderHook::SIDEBAR_NAV_END)
   

7. "Create Another" Behavior: Override the default "create another" action for all resources:

   QuickCreatePlugin::make()->createAnother(false) // Disable globally
   

Integration Tips

1. Resource-Specific Overrides: If a resource has a custom createAnother() method in its CreateAction, QuickCreate respects it by default. Use createAnother(false) to disable it globally if needed.

2. Localization: The plugin supports translations (e.g., ckb for keyboard shortcuts). Ensure your Filament locale files include the plugin's translation keys.

3. Testing:

   • Test with resources that have different create form complexities (e.g., simple vs. multi-step forms) to verify modal/redirect behavior.
   • Verify authorization: Only resources where the user has create permission should appear.

4. Performance:

   • The plugin dynamically filters resources based on user permissions, so it’s lightweight.
   • For large numbers of resources, consider using includes() to limit the dropdown size.

5. Multi-Tenant Apps: Use the hidden() callback to conditionally disable QuickCreate for tenants (e.g., during setup):

   ->hidden(fn() => Filament::getTenant()->isIncomplete())
   

Gotchas and Tips

Pitfalls

1. Theme Dependency:

   • Issue: The plugin requires a custom Filament theme. Forgetting to add the @source directive to your theme CSS will break the dropdown.
   • Fix: Always include:

     @source '../../../../vendor/awcodes/filament-quick-create/resources/**/*.blade.php';
     

2. Resource Registration Timing:

   • Issue: If resources are registered dynamically (e.g., via service providers), QuickCreate may not detect them immediately.
   • Fix: Ensure all resources are registered before the panel is initialized. Use booted() methods or lazy-load resources.

3. Authorization Caching:

   • Issue: Filament’s authorization gates might be cached, causing QuickCreate to show/hide resources incorrectly.
   • Fix: Clear cached gates or use php artisan filament:cache-reset if needed.

4. Modal Customization Conflicts:

   • Issue: Custom modal attributes (e.g., extraModalAttributes) may conflict with QuickCreate’s defaults.
   • Fix: Use the extraModalAttributes method to override:

     QuickCreatePlugin::make()->extraModalAttributes(['max-width' => '800px'])
     

5. Keyboard Shortcut Conflicts:

   • Issue: Shortcuts like command+shift+a might conflict with browser/OS defaults.
   • Tip: Test shortcuts across browsers and devices. Use less common combos (e.g., ctrl+alt+n).

6. Resource Label Fallbacks:

   • Issue: If a resource’s getTitle() method returns null, the dropdown may display [object] or break.
   • Fix: Ensure all resources implement getTitle() properly or override the label in QuickCreate:

     QuickCreatePlugin::make()->customLabels([
         UserResource::class => 'Users',
     ]);
     

Debugging Tips

1. Log Resource Detection: Add temporary logging to verify which resources are being detected:

   QuickCreatePlugin::make()->registerUsing(function (QuickCreatePlugin $plugin) {
       \Log::info('Registered resources:', $plugin->getResources());
   });
   

2. Inspect Render Hooks: If the plugin isn’t appearing, check the render hook:

   QuickCreatePlugin::make()->renderUsingHook(PanelsRenderHook::HEADER_END);
   

   Verify the hook exists in Filament’s docs.

3. Clear Caches: After making changes, run:

   php artisan optimize:clear
   php artisan view:clear
   

4. Check for JavaScript Errors: Open browser dev tools (F12) and inspect the console for errors when clicking the dropdown or using shortcuts.

Extension Points

1. Customize the Dropdown Menu: Override the default Blade view by publishing the plugin’s views:

   php artisan vendor:publish --tag="filament-quick-create-views"
   

   Then modify resources/views/vendor/filament-quick-create/....

2. Dynamic Resource Filtering: Extend the plugin to filter resources dynamically (e.g., by tenant or role):

   QuickCreatePlugin::make()->filterResources(function (array $resources) {
       return collect($resources)->reject(fn($resource) => $resource instanceof AdminResource);
   });
   

3. Add Custom Actions: Extend the dropdown to include non-resource actions (e.g., "Import Data"):

   QuickCreatePlugin::make()->customActions([
       'import' => [
           'label' => 'Import',
           'icon' => 'heroicon-o-upload',
           'url' => route('filament.admin.resources.import.create'),
       ],
   ]);
   

4. Hook into Create Events: Listen for when a resource is created via QuickCreate:

   QuickCreatePlugin::make()->created(function ($record) {
       \Log::info("Created {$record->getModel()->getMorphClass()} via QuickCreate");
   });
   

5. Localize Shortcuts: Override the default shortcuts for specific locales:

   QuickCreatePlugin::make()->keyBindings([
       'command+shift+a', // Default
       'ctrl+shift+n',    // Fallback for non-Mac users
   ]);