Skip to content

Commit abbad72

Browse files
ringungerringunger
authored
Merge pull request #1
1.x
2 parents b5d3bfa + 4217599 commit abbad72

File tree

6 files changed

+314
-110
lines changed

6 files changed

+314
-110
lines changed

‎CHANGELOG.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
## v1.0.1 (2024-05-21)
2+
3+
### Added
4+
* Support for grouped collections: Added support for grouping collections using the `groupBy` method.
5+
* Support for data attributes: Added support for specifying data attributes for the selectable items using the `withDataAttribute` method.
6+
* Support for classes: Added support for adding classes to the selectable items using the `withClass` method.
7+
8+
### Improved
9+
* Performance optimization option rendering
10+
11+
## v1.0.0 (2024-05-20)
12+
First release

‎README.md‎

Lines changed: 122 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
11
# Laravel Selectable
2-
32
[![Latest Version on Packagist](https://img.shields.io/packagist/v/ringlesoft/laravel-selectable.svg?style=flat-square)](https://packagist.org/packages/ringlesoft/laravel-selectable)
4-
[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/ringlesoft/laravel-selectable/run-tests.yml?branch=main&label=tests&style=flat-square)](https://github.com/ringlesoft/laravel-selectable/actions?query=workflow%3Arun-tests+branch%3Amain)
5-
[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/ringlesoft/laravel-selectable/fix-php-code-style-issues.yml?branch=main&label=code%20style&style=flat-square)](https://github.com/ringlesoft/laravel-selectable/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain)
63
[![Total Downloads](https://img.shields.io/packagist/dt/ringlesoft/laravel-selectable.svg?style=flat-square)](https://packagist.org/packages/ringlesoft/laravel-selectable)
7-
<!--delete-->
8-
---
9-
A laravel package for generating HTML select options from laravel collections. You do not need to add any trait or extend any class.
4+
***
5+
Laravel Selectable is a powerful package that simplifies the process of generating HTML select options from Laravel
6+
collections. With its flexible and intuitive syntax, you can easily create customized select options without the need
7+
for
8+
additional traits or class extensions.
9+
10+
## Features
11+
12+
- Generate select options from Laravel collections with ease
13+
- Customize label and value fields using strings or closures
14+
- Specify selected and disabled options
15+
- Add data attributes and classes to options
16+
- Support for grouping options
17+
- Convert collections to an array of selectable items for AJAX responses or SPAs
18+
- Utilize the power Laravel's collections for more advanced filtering and sorting
1019

1120
## Installation
1221

@@ -16,81 +25,140 @@ You can install the package via composer:
1625
composer require ringlesoft/laravel-selectable
1726
```
1827

19-
You can publish the config file with:
20-
21-
```bash
22-
php artisan vendor:publish --tag="laravel-selectable-config"
23-
```
24-
25-
This is the contents of the published config file:
26-
27-
```php
28-
return [
29-
"css_library" => "tailwind",
30-
];
31-
```
32-
33-
Optionally, you can publish the views using
34-
35-
```bash
36-
php artisan vendor:publish --tag="laravel-selectable-views"
37-
```
28+
<small> No additional configuration is required.</small>
3829

3930
## Usage
4031

4132
### 1. Basic Usage
33+
4234
```html
43-
<select name="user_id" >
35+
<select name="user_id">
4436
{!! \\App\\Model\\User::all()->toSelectOptions(); !!}}
4537
</select>
4638
```
47-
The output for this code will be as follows
39+
40+
This will generate a select dropdown with options for all users, using the name field as the label and the id field as
41+
the value.
4842

4943
```bladehtml
50-
<option value="{{$user->id}}">{{$user->name}}</option>
51-
...
44+
<select name="user_id">
45+
<option value="{{$user->id}}">{{$user->name}}</option>
46+
...
47+
</select>
5248
```
5349

54-
### 2. Custom text and value for options
50+
### 2. Inline Customization
51+
5552
```bladehtml
56-
<select name="user_id" >
57-
{!! \\App\\Model\\User::all()->toSelectOptions('email', 'uuid'); !!}}
53+
<select name="user_id">
54+
{!! \\App\\Model\\User::all()->toSelectOptions('email', 'uuid', '6490132934f22'); !!}}
5855
</select>
5956
```
60-
The output for this code will be as follows
57+
58+
This will generate a select dropdown with options for all users, using the `email` field as the label and the `uuid`
59+
field
60+
as the value. The selected option will be the user with the `uuid` 6490132934f22.
6161

6262
```bladehtml
63-
<option value="{{$user->uuid}}">{{$user->email}}</option>
64-
...
63+
<select name="user_id">
64+
<option value="{{$user->uuid}}" {{($user->uuid === '6490132934f22') ? 'selected' : '')}}>{{$user->email}}</option>
65+
...
66+
</select>
6567
```
6668

67-
### 3. Advanced use
68-
The method `toSelectable` is used to convert the collection into a `Selectable` object. The `Selectable` object has several methods that allow you to customize the options and their properties.
69+
#### Method parameters
70+
71+
- `label`: The name of the field to be used as the label for the option. If a closure is provided, the result of the
72+
closure will be used as the label. Default is `name`.
73+
- `value`: The name of the field to be used as the value for the option. If a closure is provided, the result of the
74+
closure will be used as the value. Default is `id`.
75+
- `selected`: The value of the item to be used as the selected option. Can be value, array of values or closure.
76+
- `disabled`: The value of the item to be used as the disabled option. Can be value, array of values or closure.
77+
78+
### 3. Advanced Usage
79+
80+
This package allows building of select options from a `Selectable` object using method chaining.
81+
The method `toSelectable()` is used to convert the collection into a `Selectable` object. The `Selectable` object has
82+
several methods that allow you to customize the options and their properties. The `toSelectOptions` method is used to
83+
convert the `Selectable` object into html select options.
6984

7085
```bladehtml
7186
<select name="user_id" multiple="multiple">
7287
{!!
73-
$x = \App\Models\User::all()
74-
->toSelectable()
75-
->withValue('id')
76-
->withLabel(fn($user) => "{$user->first_name} {$user->last_name}")
77-
->withSelected([4, 5])
78-
->withDisabled(fn($item) => $item->status = 'inactive')
79-
->toSelectOptions();
88+
\App\Models\User::all()
89+
->toSelectable()
90+
->withValue('id')
91+
->withLabel(fn($user) => "{$user->first_name} {$user->last_name}")
92+
->withSelected([2, 3])
93+
->withDisabled(fn($item) => $item->status = 'inactive')
94+
->withDataAttribute('hidden', fn($item) => $item->status !== 'active')
95+
->withClass('form-option custom')
96+
->toSelectOptions();
8097
!!}
8198
</select>
8299
```
83-
### 4. Available methods
84-
- `toSelectable()`: This method returns the current selectable object.
85-
- `withLabel(string|callable $label)`: This method allows you to customize the label for each option. A string will be used as the collection field from which the label will be generated, while a callable will be used to generate the label.
86-
- `withValue(string|callable $value)`: This method allows you to customize the value for each option. A string will be used as the collection field from which the value will be generated, while a callable will be used to generate the value.
87-
- `withSelected(mixed|callable $selected)`: This method allows you to customize the selected options. Can be a `string`, `int`, an array of `string`/`int`, a `model` or a callable that returns a boolean value.
88-
- `withDisabled(mixed|callable $disabled)`: This method allows you to customize the disabled options. Can be a `string`, `int`, an array of `string`/`int`, a `model` or a callable that returns a boolean value.
100+
101+
This will generate a multi-select dropdown with options for all users, using the `id` field as the `value`, and a
102+
combination of the `first_name` and `last_name` fields as the `label`. Options with IDs `2` and `3` will be selected by
103+
default,
104+
and options with an '`inactive`' `status` will be disabled. A '`data-hidden`' attribute will be added to options with
105+
a `status`
106+
other than '`active`', and a custom class '`form-option custom`' will be applied to all options.
107+
108+
```bladehtml
109+
<select name="user_id" multiple="multiple">
110+
<option value="1" data-hidden="false" class="form-option custom">David Moore</option>
111+
<option value="2" data-hidden="false" class="form-option custom">John Doe</option>
112+
<option value="3" data-hidden="false" class="form-option custom">Jane Doe</option>
113+
<option value="4" data-hidden="true" class="form-option custom" disabled>Mark Manson</option>
114+
</select>
115+
```
116+
117+
#### Available methods
118+
119+
- `withLabel(string|callable $label)`: This method allows you to customize the label for each option. A string will be
120+
used as the collection field from which the label will be generated, while a callable will be used to generate the
121+
label.
122+
- `withValue(string|callable $value)`: This method allows you to customize the value for each option. A string will be
123+
used as the collection field from which the value will be generated, while a callable will be used to generate the
124+
value.
125+
- `withSelected(mixed|callable $selected)`: This method allows you to customize the selected options. Can be
126+
a `string`, `int`, an array of `string`/`int`, a `model` or a callable that returns a boolean value.
127+
- `withDisabled(mixed|callable $disabled)`: This method allows you to customize the disabled options. Can be
128+
a `string`, `int`, an array of `string`/`int`, a `model` or a callable that returns a boolean value.
129+
- `withDataAttribute(string $attribute, mixed|callable $value)`: This method allows you to add a data attribute to each
130+
option.
131+
- `withClass(string $class)`: This method allows you to add a class to each option.
132+
- `toSelectItems()`: This method converts the selectable collection to an array of selectable items. Useful for Ajax
133+
responses or SPA.
89134
- `toSelectOptions()`: This method converts the selectable collection to an HTML select options string.
90-
- `toSelectItems()`: This method converts the selectable collection to an array of selectable items. Useful for Ajax responses or SPA.
91-
-
135+
- Some of the methods from `Illuminate\Support\Collection` are also available including `groupBy()`.
136+
137+
> <small><strong>Note:</strong> Writing queries within blade templates is not recommended. This is only for simplifying
138+
> demonstration</small>
139+
140+
## Get Selectable Items
141+
```php
142+
$selectableItems = \App\Models\User::all()->toSelectable()->toSelectItems();
143+
```
144+
This will convert the collection of users into an array of selectable items, which can be useful for AJAX responses or
145+
Single Page Applications (SPAs).
146+
147+
#### Structure of Selectable Items
148+
```json
149+
[
150+
[
151+
'label' => 'User Name',
152+
'value' => 'user_id',
153+
'selected' => false,
154+
'disabled' => false,
155+
'dataAttributes' => ['hidden' => false],
156+
'classes' => ['form-option', 'custom'],
157+
],
158+
[...]
159+
]
160+
```
92161

93-
> <small><strong>Note:</strong> Writing queries within blade templates is not recommended. This is only for simplifying demonstration</small>
94162

95163
## Testing
96164

@@ -112,7 +180,7 @@ Please review [our security policy](../../security/policy) on how to report secu
112180

113181
## Credits
114182

115-
- [David Ringle](https://github.com/ringunger)
183+
- [David Ringle](https://github.com/ringunger) (Author)
116184
- [All Contributors](../../contributors)
117185

118186
## License

‎composer.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@
5151
"name": "master"
5252
}
5353
},
54-
"version": "1.0.0",
54+
"version": "1.0.1",
5555
"minimum-stability": "dev",
5656
"prefer-stable": true
5757
}

‎src/LaravelSelectableServiceProvider.php‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33
namespace RingleSoft\LaravelSelectable;
44

5+
use Closure;
56
use Illuminate\Support\Collection;
67
use Illuminate\Support\ServiceProvider;
78

@@ -18,8 +19,13 @@ public function boot(): void
1819
$this->mergeConfigFrom(
1920
__DIR__ . '/../config/laravel_selectable.php', 'laravel_selectable'
2021
);
21-
Collection::macro('toSelectOptions', function ( $text = null, $value = null, $selected = null) {
22-
return Selectable::collectionToSelectOptions($this, $text, $value, $selected);
22+
Collection::macro('toSelectOptions', function (
23+
string|Closure|null $label = null,
24+
string|Closure|null $value = null,
25+
mixed $selected = null,
26+
mixed $disabled = null
27+
) {
28+
return Selectable::collectionToSelectOptions($this, $label, $value, $selected, $disabled);
2329
});
2430
Collection::macro('toSelectable', function () {
2531
return Selectable::fromCollection($this);

0 commit comments

Comments
 (0)