Searchable
Project wide searching dependency for Laravel Enso.
This package works exclusively within the Enso ecosystem.
The front end assets that utilize this api are present in the ui package.
For live examples and demos, you may visit laravel-enso.com
click on the photo to view a short demo in compatible browsers
Installation
Comes pre-installed in Enso.
Features
- can search for any configured model
- various actions are contextually available for each result, also depending on permissions
- the icons used for the actions are customizable
- the number is limited (by default at 10 results per model) to avoid too many DB hits
- any model may be added to the searchable list
- per-model customizations are available, such as attributes to search and the label to use when showing results
Note: Although available result model actions are shown based on the current user's permissions for that model, care must be taken when due to the search functionality, results could be listed that user might not be meant to see.
It is recommended to look into and use global query scopes for these scenarios.
Usage
Configuration
The package needs to be configured by specifying the models we want searchable. The configuration file can be found
at config/searchable.php
The following parameters are available:
defaultLabel
- the default label attribute to be used for all models, unless overwritten on the model specific configuration (see below) | default isname
routes
- customizes the icons used for the routes (remember to also have the icons available/imported)show
, default iseye
edit
, default ispencil-alt
index
, default islist-ul
limit
- the max limit of results per model. Keep in mind that more results may be available, so if looking for a specific result, be more specific when searching | default is10
models
- the list of models and their configurations that are searchable by the package
Model Configuration
Each model can be configured with a mix of required and optional attributes
User::class => [
'group' => 'User',
'attributes' => ['first_name', 'last_name', 'email'],
'label' => 'fullName',
'permissionGroup' => 'administration.users',
'scopes' => ['active'],
],
group
- string, the name of the group this model belongs to, used to group the results. If not given, the class spaced base name is used, e.g. "User", "Permission Group" | (optional)attributes
- array, the list of model attributes that we want to look at when searching | requiredlabel
- string, the model attribute we want to use as representation of the model, optional. If given, this configuration option overrides the global defaultdefaultLabel
option. Note that a computed attribute can be given as well | (optional)permissionGroup
- string, the name of the permission group to use when displaying action options for this model's results | requiredpermissions
- array, the list of permissions to be used for this model's results action options. If not given, actions are displayed (based on permissions) forindex
,show
andedit
| (optional)scopes
- array, the list of scopes to be used when querying the model | (optional)
Publishes
php artisan vendor:publish --tag=searchable-config
- configuration filephp artisan vendor:publish --tag=enso-config
- a common alias for when wanting to update the config, once a newer version is released, can be used with the--force
flag
Contributions
are welcome. Pull requests are great, but issues are good too.
License
This package is released under the MIT license.