Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/daguilarm/livewire-combobox
A laravel Livewire Dynamic Selects with multiple selects depending on each other values, with infinite levels and totally configurable.
https://github.com/daguilarm/livewire-combobox
combobox dynamics forms laravel livewire multiselect selects
Last synced: about 1 month ago
JSON representation
A laravel Livewire Dynamic Selects with multiple selects depending on each other values, with infinite levels and totally configurable.
- Host: GitHub
- URL: https://github.com/daguilarm/livewire-combobox
- Owner: daguilarm
- License: mit
- Created: 2021-04-30T11:15:17.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-02-11T16:08:12.000Z (almost 2 years ago)
- Last Synced: 2024-05-20T16:30:01.052Z (7 months ago)
- Topics: combobox, dynamics, forms, laravel, livewire, multiselect, selects
- Language: PHP
- Homepage:
- Size: 301 KB
- Stars: 25
- Watchers: 3
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
[](https://packagist.org/packages/daguilarm/livewire-combobox)
[](https://github.styleci.io/repos/363116482)
# Livewire Combobox: A dynamic selects for Laravel Livewire
A Laravel Livewire multiple selects depending on each other values, with infinite levels of dependency and totally configurable.
## Requirements
This package need at least:
- PHP ^8.0
- Laravel ^8.0
- Laravel Livewire ^2.0
- TailwindCSS ^2.0
## Installation
You can install the package via composer:
composer require daguilarm/livewire-combobox
Add the package styles in the `` using the helper `@LivewireComboboxCss`:
```html
@LivewireComboboxCss
...
```
# Documentation
## General Methods
The first thing you have to do is create a component in your folder **Livewire**. Below you can see an example using three selects:
```php
uriKey('key-for-car')
->options(function($model) {
return $model
->pluck('name', 'id')
->toArray();
}),
Select::make('Options for cars', Option::class)
->uriKey('key-for-options')
->dependOn('key-for-car')
->foreignKey('car_id')
->selectRows('id', 'option'),
Select::make('Extras for cars')
->model(Extra::class)
->firstRemoved()
->hideOnEmpty()
->uriKey('key-for-extras')
->dependOn('key-for-options')
->foreignKey('option_id')
->selectRows('id', 'extra')
->withoutResponse(),
];
}
}
```
The **package** supports infinite dependent elements. The method `elements()` should return an array with all the elements.
Let's see how the class works `Select::class` and its methods:
#### make()
The method `make()`, has the following structure:
```php
Select::make(string $label, ?string $model = null);
```
#### model()
As it can be seen, the attribute `$model` is optional in the `make()` method, and it can be added using the method `model()`:
```php
Select::make('My label')->model(User::class);
```
> :warning: Defining the model is mandatory, but it can be done in the two ways described.
#### uriKey()
This method is mandatory, it is used to define a unique key for the element.
#### hideOnEmpty()
Dependent children are removed if they are empty, instead of showing an empty field.
#### withoutResponse()
When we want an element does not send a response to the component and works only as a form field, that is, remove all the Laravel Livewire code from it. Very useful when it comes to the last selectable element and we don't want to send a request to the server.
## Child elements
These elements have their own methods, apart from those described above.
These child elements do not need the method `options()`, although it can be added if desired. The child specific methods are described below:
### dependOn()
With this method we define the parent element on which our child element depends. We must use the `uriKey` from the parent element. The basic structure of the method is:
```php
dependOn(?string $parentUriKey = null, ?string $foreignKey = null)
```
As can be seen, it admits a second value which is the *foreing key* that links the two models: **Parent** and **Child**.
### foreignKey()
This second field can also be added in two ways:
```php
// Option 1
Select::make(...)
->dependOn('key-for-options', 'option_id');
// Option 2
Select::make(...)
->dependOn('key-for-options')
->foreignKey('option_id');
```
### selectRows()
It is used to select the fields from the table that we want to load in the child element.
#### disabledOnEmpty()
If you want to disabled the field while it is empty...
## Field Types
At the moment, the package support the folowing field types:
### Select field
These fields have the following methods:
#### options()
It is used to add the values that will be shown in the element **select**. We can directly add an `array` with the values, or define a `callback`. The two values returned by the `array`: key and value, are shown as follows in the **Blade** template:
```php
// The array
[
1 => 'Car',
2 => 'Bike',
3 => 'Plane'
]
//Will be render as
Car
Bike
Plane
```
Therefore, in the component example (will be reverse):
```php
// The array
Select::make(...)
->options(function($model) {
return $model
->pluck('name', 'id')
->toArray();
})
//Will be render as
name
```
#### firstRemoved()
By default, each item will show a select field with an empty `option` element:
```html
// Element
...
```
If you want to remove it, you can add the method `firstRemoved()`.
### Search field
comming soon...
## Loading...
You can activate or deactivate the loading state, modifying the attribute `$loading`, in your component:
```php
```
We can modify the styles of the *Main Container* from the component that we created at the beginning of the documentation, using the `$comboboxContainerClass`:
```php
uriKey('key-for-car')
->options(function($model) {
return $model
->pluck('id', 'name')
->toArray();
})
->class('p-4', 'text-green-600', 'text-lg'),
```
We can use the new functionality of **php 8** to modify only those parts that interest us, or we can use the method directly:
```php
// Method 1
Select::make(...)
->class(
container: 'p-4',
field: 'text-lg',
),
// Method 2
Select::make(...)
->class('p-4', null, 'text-lg'),
```
The order of the parameters is:
```php
class(?string $container = null, ?string $label = null, ?string $field = null)
```
## Changelog
Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
## Contributing
Please see [CONTRIBUTING](CONTRIBUTING.md) for details.
### Security
If you discover any security related issues, please email [email protected] instead of using the issue tracker.
## Credits
- [Damián Aguilar](https://github.com/daguilarm)
- [All Contributors](../../contributors)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.