Download the PHP package asmit/filament-mention without Composer
On this page you can find all versions of the php package asmit/filament-mention. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download asmit/filament-mention
More information about asmit/filament-mention
Files in asmit/filament-mention
Package filament-mention
Short Description A Laravel Filament package for implementing a customizable mention editor with support for tagging users or entities.
License MIT
Informations about the package filament-mention
Filament Mention
The Mention plugin allows you to easily mention users in your Filament application using the Filament RichText editor. It supports extracting specific fields from the mentioned user, such as their username, and id. The plugin offers both static search (preloaded data) and dynamic search (real-time database queries) for mentions.
Features
- Mention users in the Filament RichText editor.
- Extract specific fields from the mentioned user (e.g. username, id).
- Static search: Preload and search from a dataset.
- Dynamic search: Fetch data from the database in real-time.
- Customizable user model and fields: Use your own
User
model and define which fields to display. - Multiple trigger characters: Use different characters like
@
,#
,%
to trigger different types of mentions. - Global object search: Search across all properties of an object without requiring a specific lookup key.
- Prefix and suffix support: Add custom text before and after mentions (e.g.,
%VARIABLE%
). - Customizable title and hint fields: Configure which fields to use for display in the dropdown menu.
- Customizable suggestion limits: Control the number of suggestions displayed and the minimum text length to trigger the search.
- Avatar and URL support: Display user avatars and link to their profiles.
Requirements
- Filament 3.2 or higher
Installation
-
Install the package via Composer:
-
After installation and update please run the following command to publish the assets:
- Publish the configuration file:
This will create a filament-mention.php
file in your config
directory. You can customize the configuration according to your needs.
Upgrading from 1.x to 2.x
If you are upgrading from version 1.x to 2.x, please note these changes:
- The configuration key
search_key
is nowsearch_column
. - The
HasMentionable
trait is nowHasMentionableForm
. - The
mentionsItems
method is nowmentionableItems
. -
The form data structure after pluck is change.
- The
FetchMentionEditor
is deprecated. You can use dynamic search withgetMentionableItemsUsing
method in theRichMentionEditor
field.
Configuration
The configuration file (config/filament-mention.php
) allows you to customize the plugin behavior. Here's an example configuration:
Key Configuration Options:
mentionable.model
: The Eloquent model to use for mentions (e.g. User).mentionable.column
: Map the fields to use for mentions (e.g. id, name, etc.).mentionable.url
: URL pattern for the mention item (e.g. admin/users/{id}).mentionable.lookup_key
: Used for static search (key in the dataset).mentionable.search_column
: Used for dynamic search (database column).default.trigger_with
: Character to trigger mentions (e.g. @).default.menu_show_min_length
: Minimum characters to type before showing suggestions.default.menu_item_limit
: Maximum number of suggestions to display.mentionable.model
: The Eloquent model to use for mentions (e.g. User).mentionable.column
: Map the fields to use for mentions (e.g. id, name, etc.).mentionable.url
: URL pattern for the mention item (e.g. admin/users/{id}).mentionable.lookup_key
: Used for static search (key in the dataset).mentionable.search_key
: Used for dynamic search (database column).default.trigger_with
: Character(s) to trigger mentions (e.g. @, #, %). Can be a string or an array.default.trigger_configs
: Configuration for specific trigger characters.default.menu_show_min_length
: Minimum characters to type before showing suggestions.default.menu_item_limit
: Maximum number of suggestions to display.default.prefix
: Default prefix to add before mentions.default.suffix
: Default suffix to add after mentions.default.title_field
: Default field to use for title display in dropdown.default.hint_field
: Default field to use for hint display in dropdown.
Recommendations:
- Use cache to store the mentionable data for static search.
- Add indexes to the columns used for dynamic search.
- If you are use mention editor inside the modal, please disable grammarly extension by
disableGrammarly()
.
Usage
1. Static Search
Static search preloads all mentionable data and searches within that dataset. For static search you can you RichMentionEditor
field.
The RichMentionEditor
fetch all the mentionable data first and then search the mention item from the fetched data.
You can also change the data by pass the closure function mentionableItems
in the RichMentionEditor
field.
example:
Key Points
- The
mentionableItems
method should return an array of mentionable items. - The most convenient way to use the
mentionableItems
method is to use theMentionItem
DTO. - Use the
lookup_key
to search the mentionable item. You can change thelookup_key
with chaining the methodlookupKey
in theRichMentionEditor
field.
NOTE: If you not use
mentionableItems
then it will use the configuration from config file.
2. Dynamic Search
To enable this feature you need to use the HasMentionableForm
in to your livewire page.
Next, you can search the mentionable data from the database using the getMentionableItemsUsing
method in the RichMentionEditor
field.
Pluck
The plugin allows you to extract specific fields from the mentioned user. You can use the pluck
method to extract the fields.
This feature helps you to customize the mention output according to your needs.
The pluck
method accepts the key
to extract the field from the mentioned user. The key should be id
or username
.
It extracts the data from the MentionItem and return the data in the array format.
It will add the new data attribute named mentioned_[YOUR PLUCK LEY]
.
If you inspect the data it will return like
Advanced Features
Multiple Trigger Characters
You can use different characters to trigger different types of mentions. This is useful when you want to mention different types of entities (e.g., users, tags, variables).
You can also configure each trigger character separately:
Global Object Search
The plugin now supports searching across all properties of an object without requiring a specific lookup key. This makes it easier to find matches regardless of which field contains the search text.
Prefix and Suffix
You can add custom text before and after mentions. This is particularly useful for variables or special formatting.
You can also configure prefix and suffix for specific trigger characters:
Customizable Title and Hint Fields
You can configure which fields to use for the title and hint in the dropdown menu:
Or for specific trigger characters:
Example: Variables with Prefix and Suffix
Here's an example of using the plugin to insert variables with % prefix and suffix:
Credits
- Asmit Nepal
- Kishan Sunar
- Jordan Humphreys (Creator of TributeJs)
Security
If you discover a security vulnerability within this package, please send an e-mail to [email protected], All security vulnerabilities will be promptly addressed.
🤝 Contributing
Please see CONTRIBUTING for details.
📄 License
The MIT License (MIT). Please see License File for more information.
Made with love by Asmit Nepali