Filament Quick Notes Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require rarq/filament-quick-notes
   php artisan filament-quick-notes:install
   

   This publishes the config file and migrations.

2. Register the Plugin: Add to your PanelProvider:

   use Rarq\FilamentQuickNotes\FilamentQuickNotesPlugin;
   
   $panel->plugins([
       FilamentQuickNotesPlugin::make(),
   ]);
   

3. Enable on User Model: Add the trait to your user model:

   use Rarq\FilamentQuickNotes\Traits\HasFilamentQuickNotes;
   
   class User extends Authenticatable
   {
       use HasFilamentQuickNotes;
   }
   

First Use Case

Quickly jot down a reminder while working in Filament:

• Click the sticky-note icon in the topbar (default: left of the search bar).
• Type a note, assign a color, and save.
• Reorder notes by dragging or using the "Move Up/Down" buttons.

Implementation Patterns

Core Workflow

1. Staged Editing:

   • Create or edit notes in-memory; changes appear immediately but aren’t saved until you click "Save Changes".
   • Useful for rapid note-taking without cluttering the UI with confirmation dialogs.

2. Conditional Visibility:

   • Hide/show the plugin based on user roles or permissions:

     FilamentQuickNotesPlugin::make()
         ->visible(fn () => auth()->user()->hasRole('admin')),
     

3. Positioning:

   • Customize where the button appears in the panel:

     'position' => \Filament\View\PanelsRenderHook::TOPBAR_START,
     

   • Options: GLOBAL_SEARCH_BEFORE (default), GLOBAL_SEARCH_AFTER, TOPBAR_START/END.

4. Multi-Tenancy:

   • Works seamlessly with polymorphic user models (e.g., User, TenantUser). Notes are scoped to the authenticated user.

Integration Tips

• Localization: The plugin supports multilingual labels (e.g., "Notes", "Save Changes"). Override via language files or config.

• Custom Models: Extend FilamentQuickNote or implement the same interface to use a custom model:

  'quick_notes_model' => App\Models\CustomQuickNote::class,
  

• Deletion Behavior: Choose between soft-deletes (default) or permanent deletion:

  'deletion_type' => \Rarq\FilamentQuickNotes\Enums\DeletionType::FORCE,
  

• Styling: Override the Blade view (resources/views/vendor/filament-quick-notes/...) to match your panel’s theme.

Gotchas and Tips

Pitfalls

1. Migration Conflicts:

   • If you rename the default table (filament_quick_notes), ensure the HasFilamentQuickNotes trait’s notes() relation matches:

     public function notes()
     {
         return $this->hasMany(\Rarq\FilamentQuickNotes\Models\FilamentQuickNote::class, 'user_id');
     }
     

2. Unsaved Changes Guard:

   • The plugin blocks panel closure if notes are unsaved. Disable this behavior by overriding the shouldPreventPanelClose() method in your custom model.

3. Caching:

   • Staged changes are stored in-memory. If using Filament’s cache, ensure it doesn’t interfere with the plugin’s session storage.

Debugging

• Missing Button: Verify the plugin is registered in PanelProvider and the user model has the HasFilamentQuickNotes trait.

• Notes Not Saving: Check the filament_quick_notes table for records. If using soft deletes, inspect the deleted_at column.

• Permission Issues: Ensure the user model’s notes() relation is accessible (e.g., no visible/appends conflicts).

Extension Points

1. Custom Actions: Add buttons to individual notes via the actions config:

   'note_actions' => [
       'archive' => [
           'label' => 'Archive',
           'icon' => 'heroicon-o-archive',
           'color' => 'gray',
       ],
   ],
   

2. Note Metadata: Extend the FilamentQuickNote model to store additional fields (e.g., priority, due_date):

   class CustomQuickNote extends FilamentQuickNote
   {
       protected $fillable = ['content', 'color', 'priority'];
   }
   

3. API Access: Expose notes via a custom API endpoint using the same model:

   Route::get('/notes', function () {
       return auth()->user()->notes()->latest()->get();
   });
   

Pro Tips

• Keyboard Shortcuts: Bind a shortcut (e.g., Ctrl+Shift+N) to toggle the notes panel using Filament’s registerScript:

  $panel->script(function () {
      return <<<JS
          document.addEventListener('keydown', (e) => {
              if (e.ctrlKey && e.shiftKey && e.key === 'N') {
                  document.querySelector('[data-testid="quick-notes-toggle"]').click();
              }
          });
      JS;
  });
  

• Team Collaboration: Use the plugin for team-wide notes by storing notes on a shared model (e.g., Team) instead of the user model. Override the relation in the trait:

  public function notes()
  {
      return $this->belongsToMany(Team::class)->withPivot('content', 'color');
  }