\ No newline at end of file
diff --git a/docs/column-types/avg_column.md b/docs/column-types/avg_column.md
new file mode 100644
index 000000000..f0f7680ac
--- /dev/null
+++ b/docs/column-types/avg_column.md
@@ -0,0 +1,30 @@
+---
+title: Avg Columns (beta)
+weight: 3
+---
+
+Avg columns provide an easy way to display the "Average" of a field on a relation.
+
+```php
+ AvgColumn::make('Average Related User Age')
+ ->setDataSource('users','age')
+ ->sortable(),
+```
+
+The "sortable()" callback can accept a callback, or you can use the default behaviour, which calculates the correct field to sort on.
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/boolean_columns.md b/docs/column-types/boolean_columns.md
new file mode 100644
index 000000000..51c3702e4
--- /dev/null
+++ b/docs/column-types/boolean_columns.md
@@ -0,0 +1,137 @@
+---
+title: Boolean Columns
+weight: 4
+---
+
+Boolean columns are good if you have a column type that is a true/false, or 0/1 value.
+
+For example:
+
+```php
+BooleanColumn::make('Active')
+```
+
+Would yield:
+
+
+
+### Using your own view
+
+If you don't want to use the default view and icons you can set your own:
+
+```php
+BooleanColumn::make('Active')
+ ->setView('my.active.view')
+```
+
+You will have access to `$component`, `$status`, and `$successValue`.
+
+To help you better understand, this is the Tailwind implementation of BooleanColumn:
+
+```html
+@if ($status)
+
+@else
+
+@endif
+```
+
+### Setting the truthy value
+
+If you want the false value to be the green option, you can set:
+
+```php
+BooleanColumn::make('Active')
+ ->setSuccessValue(false); // Makes false the 'successful' option
+```
+
+That would swap the colors of the icons in the image above.
+
+### Setting the status value
+
+By default, the `$status` is set to:
+
+```php
+(bool)$value === true
+```
+
+You can override this functionality:
+
+```php
+BooleanColumn::make('Active')
+ // Note: Parameter `$row` available as of v2.4
+ ->setCallback(function(string $value, $row) {
+ // Figure out what makes $value true
+ }),
+```
+
+### Different types of boolean display
+
+By default, the BooleanColumn displays icons.
+
+If you would like the BooleanColumn to display a plain Yes/No, you can set:
+
+```php
+BooleanColumn::make('Active')
+ ->yesNo()
+```
+
+### Toggleable
+
+You may call a defined public function, which should live within your Table Component, to allow "toggling" against your database:
+
+```php
+BooleanColumn::make('Active', 'status')
+ ->toggleable('changeStatus'),
+```
+
+Then your "changeStatus" method may look like (make sure you are selecting the `id` in the query)
+```php
+ public function changeStatus(int $id)
+ {
+ $item = $this->model::find($id);
+ $item->status = !$item->status;
+ $item->save();
+ }
+```
+
+### Toggleable Confirmation Message
+
+You may define a confirmation message prior to executing your toggleable() method. The method will only be executed upon confirming.
+```php
+BooleanColumn::make('Active', 'status')
+ ->confirmMessage('Are you sure that you want to change the status?')
+ ->toggleable('changeStatus'),
+```
+
+Then your "changeStatus" method may look like (make sure you are selecting the `id` in the query)
+```php
+ public function changeStatus(int $id)
+ {
+ $item = $this->model::find($id);
+ $item->status = !$item->status;
+ $item->save();
+ }
+```
+
+
+### Additional Methods
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/button_group_column.md b/docs/column-types/button_group_column.md
new file mode 100644
index 000000000..da8ff7399
--- /dev/null
+++ b/docs/column-types/button_group_column.md
@@ -0,0 +1,41 @@
+---
+title: Button Group Columns
+weight: 5
+---
+
+Button group columns let you provide an array of LinkColumns to display in a single cell.
+
+```php
+ButtonGroupColumn::make('Actions')
+ ->attributes(function($row) {
+ return [
+ 'class' => 'space-x-2',
+ ];
+ })
+ ->buttons([
+ LinkColumn::make('View') // make() has no effect in this case but needs to be set anyway
+ ->title(fn($row) => 'View ' . $row->name)
+ ->location(fn($row) => route('user.show', $row))
+ ->attributes(function($row) {
+ return [
+ 'class' => 'underline text-blue-500 hover:no-underline',
+ ];
+ }),
+ LinkColumn::make('Edit')
+ ->title(fn($row) => 'Edit ' . $row->name)
+ ->location(fn($row) => route('user.edit', $row))
+ ->attributes(function($row) {
+ return [
+ 'target' => '_blank',
+ 'class' => 'underline text-blue-500 hover:no-underline',
+ ];
+ }),
+ ]),
+```
+
+
+Please also see the following for other available methods:
+- [https://rappasoft.com/docs/laravel-livewire-tables/v3/columns/available-methods](Available Methods)
+- [https://rappasoft.com/docs/laravel-livewire-tables/v3/columns/column-selection](Column Selection)
+- [https://rappasoft.com/docs/laravel-livewire-tables/v3/columns/secondary-header](Secondary Header)
+- [https://rappasoft.com/docs/laravel-livewire-tables/v3/columns/footer](Footer)
diff --git a/docs/column-types/color_columns.md b/docs/column-types/color_columns.md
new file mode 100644
index 000000000..eeae20b2f
--- /dev/null
+++ b/docs/column-types/color_columns.md
@@ -0,0 +1,57 @@
+---
+title: Color Columns
+weight: 6
+---
+
+Color columns provide an easy way to a Color in a Column
+
+You may pass either pass a CSS-compliant colour as a field
+```php
+ColorColumn::make('Favourite Colour', 'favourite_color'),
+```
+
+Or you may use a Callback
+```php
+ColorColumn::make('Favourite Colour')
+ ->color(
+ function ($row) {
+ if ($row->success_rate < 40)
+ {
+ return '#ff0000';
+ }
+ else if ($row->success_rate > 90)
+ {
+ return '#008000';
+ }
+ else return '#ffa500';
+
+ }
+ ),
+```
+
+You may also specify attributes to use on the div displaying the color, to adjust the size or appearance, this receives the full row. By default, this will replace the standard classes, to retain them, set "default" to true. To then over-ride, you should prefix your classes with "!" to signify importance.
+```php
+ ColorColumn::make('Favourite Colour')
+ ->attributes(function ($row) {
+ return [
+ 'class' => '!rounded-lg self-center',
+ 'default' => true,
+ ];
+ }),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/component_column.md b/docs/column-types/component_column.md
new file mode 100644
index 000000000..79611121f
--- /dev/null
+++ b/docs/column-types/component_column.md
@@ -0,0 +1,43 @@
+---
+title: Component Columns
+weight: 7
+---
+
+Component columns let you specify a component name and attributes and provides the column value to the slot.
+
+```php
+// Before
+Column::make("Email", "email")
+ ->format(function ($value) {
+ return view('components.alert')
+ ->with('attributes', new ComponentAttributeBag([
+ 'type' => Str::endsWith($value, 'example.org') ? 'success' : 'danger',
+ 'dismissible' => true,
+ ]))
+ ->with('slot', $value);
+ }),
+
+// After
+ComponentColumn::make('E-mail', 'email')
+ ->component('email')
+ ->attributes(fn ($value, $row, Column $column) => [
+ 'type' => Str::endsWith($value, 'example.org') ? 'success' : 'danger',
+ 'dismissible' => true,
+ ]),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/count_column.md b/docs/column-types/count_column.md
new file mode 100644
index 000000000..beb7d3437
--- /dev/null
+++ b/docs/column-types/count_column.md
@@ -0,0 +1,30 @@
+---
+title: Count Columns (beta)
+weight: 8
+---
+
+Count columns provide an easy way to display the "Count" of a relation.
+
+```php
+ CountColumn::make('Related Users')
+ ->setDataSource('users')
+ ->sortable(),
+```
+
+The "sortable()" callback can accept a callback, or you can use the default behaviour, which calculates the correct field to sort on.
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/date_columns.md b/docs/column-types/date_columns.md
new file mode 100644
index 000000000..17ffa581b
--- /dev/null
+++ b/docs/column-types/date_columns.md
@@ -0,0 +1,43 @@
+---
+title: Date Columns
+weight: 9
+---
+
+Date columns provide an easy way to display dates in a given format, without having to use repetitive format() methods or partial views.
+
+You may pass either a DateTime object, in which you can define an "outputFormat"
+```php
+DateColumn::make('Updated At', 'updated_at')
+ ->outputFormat('Y-m-d H:i:s'),
+```
+
+Or you may pass a string, in which case you can define an "inputFormat" in addition to the outputFormat:
+```php
+DateColumn::make('Last Charged', 'last_charged_at')
+ ->inputFormat('Y-m-d H:i:s')
+ ->outputFormat('Y-m-d'),
+```
+
+You may also set an "emptyValue" to use when there is no value from the database:
+```php
+DateColumn::make('Last Charged', 'last_charged_at')
+ ->inputFormat('Y-m-d H:i:s')
+ ->outputFormat('Y-m-d')
+ ->emptyValue('Not Found'),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/image_columns.md b/docs/column-types/image_columns.md
new file mode 100644
index 000000000..4225593b3
--- /dev/null
+++ b/docs/column-types/image_columns.md
@@ -0,0 +1,42 @@
+---
+title: Image Columns
+weight: 11
+---
+
+Image columns provide a way to display images in your table without having to use `format()` or partial views:
+
+```php
+ImageColumn::make('Avatar')
+ ->location(
+ fn($row) => storage_path('app/public/avatars/' . $row->id . '.jpg')
+ ),
+```
+
+You may also pass an array of attributes to apply to the image tag:
+
+```php
+ImageColumn::make('Avatar')
+ ->location(
+ fn($row) => storage_path('app/public/avatars/' . $row->id . '.jpg')
+ )
+ ->attributes(fn($row) => [
+ 'class' => 'rounded-full',
+ 'alt' => $row->name . ' Avatar',
+ ]),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/increment_column.md b/docs/column-types/increment_column.md
new file mode 100644
index 000000000..76ea7496c
--- /dev/null
+++ b/docs/column-types/increment_column.md
@@ -0,0 +1,12 @@
+---
+title: Increment Column (beta)
+weight: 12
+---
+
+The IncrementColumn provides an easy way to display the row's index in the loop.
+
+Please note - this is not linked to the row's primary key!
+
+```php
+ IncrementColumn::make('#'),
+```
\ No newline at end of file
diff --git a/docs/column-types/link_columns.md b/docs/column-types/link_columns.md
new file mode 100644
index 000000000..7c36ee077
--- /dev/null
+++ b/docs/column-types/link_columns.md
@@ -0,0 +1,40 @@
+---
+title: Link Columns
+weight: 13
+---
+
+Link columns provide a way to display HTML links in your table without having to use `format()` or partial views:
+
+```php
+LinkColumn::make('Action')
+ ->title(fn($row) => 'Edit')
+ ->location(fn($row) => route('admin.users.edit', $row)),
+```
+
+You may also pass an array of attributes to apply to the `a` tag:
+
+```php
+LinkColumn::make('Action')
+ ->title(fn($row) => 'Edit')
+ ->location(fn($row) => route('admin.users.edit', $row))
+ ->attributes(fn($row) => [
+ 'class' => 'rounded-full',
+ 'alt' => $row->name . ' Avatar',
+ ]),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/livewire_component_column.md b/docs/column-types/livewire_component_column.md
new file mode 100644
index 000000000..f48859641
--- /dev/null
+++ b/docs/column-types/livewire_component_column.md
@@ -0,0 +1,31 @@
+---
+title: Livewire Component (beta)
+weight: 14
+---
+
+Livewire Component Columns allow for the use of a Livewire Component as a Column.
+
+This is **not recommended** as due to the nature of Livewire, it becomes inefficient at scale.
+
+## component
+```php
+LivewireComponentColumn::make('Action')
+ ->component('PathToLivewireComponent'),
+
+```
+
+Please also see the following for other available methods:
+
diff --git a/docs/column-types/standard_column.md b/docs/column-types/standard_column.md
new file mode 100644
index 000000000..7d5b4ede3
--- /dev/null
+++ b/docs/column-types/standard_column.md
@@ -0,0 +1,31 @@
+---
+title: Standard Column
+weight: 1
+---
+
+A standard Column has a multitude of different options, making it simple for you to display your data, as documented below:
+
+
\ No newline at end of file
diff --git a/docs/column-types/sum_column.md b/docs/column-types/sum_column.md
new file mode 100644
index 000000000..638818b23
--- /dev/null
+++ b/docs/column-types/sum_column.md
@@ -0,0 +1,30 @@
+---
+title: Sum Columns (beta)
+weight: 15
+---
+
+Sum columns provide an easy way to display the "Sum" of a field on a relation.
+
+```php
+ SumColumn::make('Total Age of Related Users')
+ ->setDataSource('users','age')
+ ->sortable(),
+```
+
+The "sortable()" callback can accept a callback, or you can use the default behaviour, which calculates the correct field to sort on.
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/view_component_column.md b/docs/column-types/view_component_column.md
new file mode 100644
index 000000000..5fdb4b46d
--- /dev/null
+++ b/docs/column-types/view_component_column.md
@@ -0,0 +1,44 @@
+---
+title: View Component Columns
+weight: 16
+---
+
+View Component columns let you specify a component name and attributes and provide attributes to the View Component. This will render the View Component in it's entirety.
+
+```php
+
+ViewComponentColumn::make('E-mail', 'email')
+ ->component('email')
+ ->attributes(fn ($value, $row, Column $column) => [
+ 'id' => $row->id,
+ 'email' => $value,
+ ]),
+```
+
+### customComponent
+
+Should you wish to render the Custom Component in it's entirety, then you may use the customComponent method. Otherwise it will pass in the values directly to the blade, rather than executing your View Component.
+
+```php
+ViewComponentColumn::make('Weight', 'grams')
+ ->customComponent(\App\View\Components\TestWeight::class)
+ ->attributes(fn ($value, $row, Column $column) => [
+ 'weight' => new Weight($value),
+ ]),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/column-types/wire_link_column.md b/docs/column-types/wire_link_column.md
new file mode 100644
index 000000000..63c23e8a2
--- /dev/null
+++ b/docs/column-types/wire_link_column.md
@@ -0,0 +1,53 @@
+---
+title: Wire Link Column (beta)
+weight: 17
+---
+
+WireLink columns provide a way to display Wired Links in your table without having to use `format()` or partial views, with or without a Confirmation Message
+
+WireLinkColumn requires title, and an "action", which must be a valid LiveWire method in the current class, or a global method
+
+Without a Confirmation Message
+```php
+ WireLinkColumn::make("Delete Item")
+ ->title(fn($row) => 'Delete Item')
+ ->action(fn($row) => 'delete("'.$row->id.'")'),
+```
+
+You may also pass a string to "confirmMessage", which will utilise LiveWire 3's "wire:confirm" approach to display a confirmation modal.
+
+```php
+ WireLinkColumn::make("Delete Item")
+ ->title(fn($row) => 'Delete Item')
+ ->confirmMessage('Are you sure you want to delete this item?')
+ ->action(fn($row) => 'delete("'.$row->id.'")')
+ ->attributes(fn($row) => [
+ 'class' => 'btn btn-danger',
+ ]),
+```
+
+And you may also pass an array of attributes, which will be applied to the "button" element used within the Column
+```php
+ WireLinkColumn::make("Delete Item")
+ ->title(fn($row) => 'Delete Item')
+ ->action(fn($row) => 'delete("'.$row->id.'")')
+ ->attributes(fn($row) => [
+ 'class' => 'btn btn-danger',
+ ]),
+```
+
+Please also see the following for other available methods:
+
\ No newline at end of file
diff --git a/docs/columns/available-methods.md b/docs/columns/available-methods.md
index ab41c7095..18f840b5d 100644
--- a/docs/columns/available-methods.md
+++ b/docs/columns/available-methods.md
@@ -3,6 +3,10 @@ title: Available Methods
weight: 3
---
+## Styling
+
+To change the CSS classes or other attributes assigned to a Column, use can use [setTdAttributes](../datatable/styling), which allows customising attributes based on column type, name or value.
+
## Sorting
See also [component sorting configuration](../sorting/available-methods).
@@ -25,7 +29,7 @@ Column::make(__('Address'))
### [Multi-column sorting](../sorting/available-methods#setsinglesortingstatus)
-In v2, multi-column sorting is **disabled by default**. To enable it you can set the `setSingleSortingDisabled()` method on the component.
+Multi-column sorting is **disabled by default**. To enable it you can set the `setSingleSortingDisabled()` method on the component.
```php
public function configure(): void
@@ -156,6 +160,23 @@ Column::make('My one off column')
),
```
+Note that any field not used elsewhere in the table, that is required (for example creating an attribute based on two unused fields, these must be added to the query with setAdditionalSelects() in the configure() method (See Here)[https://rappasoft.com/docs/laravel-livewire-tables/v3/datatable/available-methods#content-builder])
+```php
+ public function configure(): void
+ {
+ $this->setAdditionalSelects(['users.forename as forename', 'users.surname as surname']);
+ }
+```
+
+You can then use the fields:
+```php
+Column::make('My one off column')
+ ->label(
+ fn($row, Column $column) => $row->forename.' '.$row->surname
+ )
+ ->html(),
+```
+
## Collapsing
The component has the ability to collapse certain columns at different screen sizes. It will add a plus icon as the left most column that will open up a view below the row with the information of the collapsed columns:
@@ -281,3 +302,7 @@ Labels are visible by default, but should you wish to override a previous "hideC
Column::make('Name')
->setColumnLabelStatusEnabled()
```
+
+## See Also
+[Column Styling](./styling)
+
diff --git a/docs/columns/column-selection.md b/docs/columns/column-selection.md
index 94c0674a5..0d5872fbb 100644
--- a/docs/columns/column-selection.md
+++ b/docs/columns/column-selection.md
@@ -23,6 +23,41 @@ Column::make('Address', 'address.address')
->deselected(),
```
+## DeselectedIf
+
+If you would like a column to be included in the column select but deselected based on an external parameter/callback, you may use this approach.
+
+Returning "true" will deselect the Column by default, returning "false" will select the Column by default
+
+```php
+Column::make('Address', 'address.address')
+ ->deselectedIf(fn() => 2 > 1),
+```
+
+or
+
+```php
+Column::make('Address', 'address.address')
+ ->deselectedIf(!Auth::user()),
+```
+
+## SelectedIf
+
+If you would like a column to be included in the column select and selected based on an external parameter/callback, you may use this approach.
+
+Returning "true" will select the Column by default, returning "false" will deselect the Column by default
+
+```php
+Column::make('Address', 'address.address')
+ ->selectedIf(fn() => 2 > 1),
+```
+or
+
+```php
+Column::make('Address', 'address.address')
+ ->selectedIf(Auth::user()),
+```
+
## Available Methods
### setColumnSelectStatus
@@ -187,4 +222,68 @@ class DataTableColumnsSelectedListener
}
}
-```
\ No newline at end of file
+```
+
+## Styling
+
+### setColumnSelectButtonAttributes
+Allows for customisation of the appearance of the "Column Select" button
+
+Note that this utilises a refreshed approach for attributes, and allows for appending to, or replacing the styles and colors independently, via the below methods.
+
+#### default-colors
+Setting to false will disable the default colors for the Column Select button, the default colors are:
+
+Bootstrap: None
+
+Tailwind: `text-gray-700 bg-white border-gray-300 hover:bg-gray-50 focus:border-indigo-300 focus:ring-indigo-200 dark:bg-gray-700 dark:text-white dark:border-gray-600 dark:hover:bg-gray-600`
+
+#### default-styling
+Setting to false will disable the default styling for the Column Select button, the default styling is:
+
+Bootstrap: `btn dropdown-toggle d-block w-100 d-md-inline`
+
+Tailwind: `inline-flex justify-center px-4 py-2 w-full text-sm font-medium rounded-md border shadow-sm focus:ring focus:ring-opacity-50`
+
+```php
+public function configure(): void
+{
+ $this->setColumnSelectButtonAttributes([
+ 'class' => 'focus:border-rose-300 focus:ring-1 focus:ring-rose-300 focus-visible:outline-rose-300', // Add these classes to the column select button
+ 'default-colors' => false, // Do not output the default colors
+ 'default-styling' => true // Output the default styling
+ ]);
+}
+```
+
+### setColumnSelectMenuOptionCheckboxAttributes
+Allows for customisation of the appearance of the "Column Select" menu option checkbox
+
+Note that this utilises a refreshed approach for attributes, and allows for appending to, or replacing the styles and colors independently, via the below methods.
+
+#### default-colors
+Setting to false will disable the default colors for the Column Select menu option checkbox, the default colors are:
+
+Bootstrap: None
+
+Tailwind: `text-indigo-600 border-gray-300 focus:border-indigo-300 focus:ring-indigo-200 dark:bg-gray-900 dark:text-white dark:border-gray-600 dark:hover:bg-gray-600 dark:focus:bg-gray-600`
+#### default-styling
+
+Setting to false will disable the default styling for the Column Select menu option checkbox, the default styling is:
+
+Bootstrap 4: None
+
+Bootstrap 5: `form-check-input`
+
+Tailwind: `transition duration-150 ease-in-out rounded shadow-sm focus:ring focus:ring-opacity-50 disabled:opacity-50 disabled:cursor-wait`
+
+```php
+public function configure(): void
+{
+ $this->setColumnSelectMenuOptionCheckboxAttributes([
+ 'class' => 'text-rose-300 focus:border-rose-300 focus:ring-rose-300', // Add these classes to the column select menu option checkbox
+ 'default-colors' => false, // Do not output the default colors
+ 'default-styling' => true // Output the default styling
+ ]);
+}
+```
diff --git a/docs/columns/footer.md b/docs/columns/footer.md
index caf9a45d4..c4b3877e7 100644
--- a/docs/columns/footer.md
+++ b/docs/columns/footer.md
@@ -21,7 +21,7 @@ See also [footer component configuration](../footer/available-methods).
## Using a filter as a footer
-As of version 2.7, you can use a filter as a footer.
+You can use a filter as a footer.
```php
// Example filter
diff --git a/docs/columns/other-column-types.md b/docs/columns/other-column-types.md
index dc80da449..f12adf6e7 100644
--- a/docs/columns/other-column-types.md
+++ b/docs/columns/other-column-types.md
@@ -3,247 +3,48 @@ title: Other Column Types
weight: 4
---
-## Boolean Columns
-
-Boolean columns are good if you have a column type that is a true/false, or 0/1 value.
-
-For example:
-
-```php
-BooleanColumn::make('Active')
-```
-
-Would yield:
-
-
-
-### Using your own view
-
-If you don't want to use the default view and icons you can set your own:
-
-```php
-BooleanColumn::make('Active')
- ->setView('my.active.view')
-```
-
-You will have access to `$component`, `$status`, and `$successValue`.
-
-To help you better understand, this is the Tailwind implementation of BooleanColumn:
-
-```html
-@if ($status)
-
-@else
-
-@endif
-```
-
-### Setting the truthy value
-
-If you want the false value to be the green option, you can set:
-
-```php
-BooleanColumn::make('Active')
- ->setSuccessValue(false); // Makes false the 'successful' option
-```
-
-That would swap the colors of the icons in the image above.
-
-### Setting the status value
-
-By default, the `$status` is set to:
-
-```php
-(bool)$value === true
-```
-
-You can override this functionality:
-
-```php
-BooleanColumn::make('Active')
- // Note: Parameter `$row` available as of v2.4
- ->setCallback(function(string $value, $row) {
- // Figure out what makes $value true
- }),
-```
-
-### Different types of boolean display
-
-By default, the BooleanColumn displays icons.
-
-If you would like the BooleanColumn to display a plain Yes/No, you can set:
-
-```php
-BooleanColumn::make('Active')
- ->yesNo()
-```
-## Color Columns
-
-Color columns provide an easy way to a Color in a Column
-
-You may pass either pass a CSS-compliant colour as a field
-```php
-ColorColumn::make('Favourite Colour', 'favourite_color'),
-```
-
-Or you may use a Callback
-```php
-ColorColumn::make('Favourite Colour')
- ->color(
- function ($row) {
- if ($row->success_rate < 40)
- {
- return '#ff0000';
- }
- else if ($row->success_rate > 90)
- {
- return '#008000';
- }
- else return '#ffa500';
-
- }
- ),
-```
-
-You may also specify attributes to use on the div displaying the color, to adjust the size or appearance, this receives the full row. By default, this will replace the standard classes, to retain them, set "default" to true. To then over-ride, you should prefix your classes with "!" to signify importance.
-```php
- ColorColumn::make('Favourite Colour')
- ->attributes(function ($row) {
- return [
- 'class' => '!rounded-lg self-center',
- 'default' => true,
- ];
- }),
-```
-
-## Date Columns
-
-Date columns provide an easy way to display dates in a given format, without having to use repetitive format() methods or partial views.
-
-You may pass either a DateTime object, in which you can define an "outputFormat"
-```php
-DateColumn::make('Updated At', 'updated_at')
- ->outputFormat('Y-m-d H:i:s),
-```
-
-Or you may pass a string, in which case you can define an "inputFormat" in addition to the outputFormat:
-```php
-DateColumn::make('Last Charged', 'last_charged_at')
- ->inputFormat('Y-m-d H:i:s')
- ->outputFormat('Y-m-d'),
-```
-
-You may also set an "emptyValue" to use when there is no value from the database:
-```php
-DateColumn::make('Last Charged', 'last_charged_at')
- ->inputFormat('Y-m-d H:i:s')
- ->outputFormat('Y-m-d')
- ->emptyValue('Not Found'),
-```
-
-## Image Columns
-
-Image columns provide a way to display images in your table without having to use `format()` or partial views:
-
-```php
-ImageColumn::make('Avatar')
- ->location(
- fn($row) => storage_path('app/public/avatars/' . $row->id . '.jpg')
- ),
-```
-
-You may also pass an array of attributes to apply to the image tag:
-
-```php
-ImageColumn::make('Avatar')
- ->location(
- fn($row) => storage_path('app/public/avatars/' . $row->id . '.jpg')
- )
- ->attributes(fn($row) => [
- 'class' => 'rounded-full',
- 'alt' => $row->name . ' Avatar',
- ]),
-```
-
-## Link Columns
-
-Link columns provide a way to display HTML links in your table without having to use `format()` or partial views:
-
-```php
-LinkColumn::make('Action')
- ->title(fn($row) => 'Edit')
- ->location(fn($row) => route('admin.users.edit', $row)),
-```
-
-You may also pass an array of attributes to apply to the `a` tag:
-
-```php
-LinkColumn::make('Action')
- ->title(fn($row) => 'Edit')
- ->location(fn($row) => route('admin.users.edit', $row))
- ->attributes(fn($row) => [
- 'class' => 'rounded-full',
- 'alt' => $row->name . ' Avatar',
- ]),
-```
-
-## Button Group Columns
-
-Button group columns let you provide an array of LinkColumns to display in a single cell.
-
-```php
-ButtonGroupColumn::make('Actions')
- ->attributes(function($row) {
- return [
- 'class' => 'space-x-2',
- ];
- })
- ->buttons([
- LinkColumn::make('View') // make() has no effect in this case but needs to be set anyway
- ->title(fn($row) => 'View ' . $row->name)
- ->location(fn($row) => route('user.show', $row))
- ->attributes(function($row) {
- return [
- 'class' => 'underline text-blue-500 hover:no-underline',
- ];
- }),
- LinkColumn::make('Edit')
- ->title(fn($row) => 'Edit ' . $row->name)
- ->location(fn($row) => route('user.edit', $row))
- ->attributes(function($row) {
- return [
- 'target' => '_blank',
- 'class' => 'underline text-blue-500 hover:no-underline',
- ];
- }),
- ]),
-```
-
-## Component Columns
-
-Component columns let you specify a component name and attributes and provides the column value to the slot.
-
-```php
-// Before
-Column::make("Email", "email")
- ->format(function ($value) {
- return view('components.alert')
- ->with('attributes', new ComponentAttributeBag([
- 'type' => Str::endsWith($value, 'example.org') ? 'success' : 'danger',
- 'dismissible' => true,
- ]))
- ->with('slot', $value);
- }),
-
-// After
-ComponentColumn::make('E-mail', 'email')
- ->component('email')
- ->attributes(fn ($value, $row, Column $column) => [
- 'type' => Str::endsWith($value, 'example.org') ? 'success' : 'danger',
- 'dismissible' => true,
- ]),
-```
+
\ No newline at end of file
diff --git a/docs/columns/reusable-columns.md b/docs/columns/reusable-columns.md
index 53b5865b2..d913d80d3 100644
--- a/docs/columns/reusable-columns.md
+++ b/docs/columns/reusable-columns.md
@@ -10,7 +10,7 @@ To mitigate the pain of maintaining this, two new methods have been introduced.
These methods both function in exactly the same way as your standard columns(), and expect an array of columns.
Any columns defined in prependColumns() will be the first columns in your list of columns.
-```
+```php
public function prependColumns(): array
{
return [];
@@ -18,7 +18,7 @@ public function prependColumns(): array
```
Any columns defined in appendColumns() will be the last columns in your list of columns.
-```
+```php
public function appendColumns(): array
{
return [];
@@ -28,7 +28,7 @@ public function appendColumns(): array
You can call these in your trait, and they will be automatically appended/prepended to tables.
For example, to append a Column for Updated At
-```
+```php
public function appendColumns(): array
{
return [
diff --git a/docs/columns/secondary-header.md b/docs/columns/secondary-header.md
index 31790b3e8..258db8d30 100644
--- a/docs/columns/secondary-header.md
+++ b/docs/columns/secondary-header.md
@@ -21,7 +21,7 @@ See also [secondary header component configuration](../secondary-header/availabl
## Using a filter as a secondary header
-As of version 2.7, you can use a filter as a header.
+You can use a filter as a header.
```php
// Example filter
diff --git a/docs/columns/styling.md b/docs/columns/styling.md
new file mode 100644
index 000000000..7862c9566
--- /dev/null
+++ b/docs/columns/styling.md
@@ -0,0 +1,302 @@
+---
+title: Styling
+weight: 10
+---
+
+## Keeping Defaults
+To allow simpler customisation on a per-table basis, there are numerous methods available to over-ride the default CSS classes.
+Historically, this was provided by a simple toggleable "default" flag. However - in many cases, the original "default" has been expanded to include:
+
+### Keep Default Colors And Default Styles
+- set default flag to true
+or
+- set default-colors flag to true
+- set default-styling flag to true
+
+### Keep Default Colors Only
+- set default flag to false
+- set default-colors flag to true
+- set default-styling flag to false
+
+### Keep Default Styling Only
+- set default flag to false
+- set default-colors flag to false
+- set default-styling flag to true
+
+## Styling The Column Label
+
+The Column itself provides the capability to style the Label shown in the "th" element. You can set custom attributes to pass to the Column Label on a per-Column basis:
+
+For example:
+```php
+Column::make('Name')
+ ->setLabelAttributes(['class' => 'text-2xl'])
+```
+By default, this replaces the default classes on the label, if you would like to keep them, set the default/default-styling/default-colors flags to true as appropriate.
+
+## Styling Table Elements
+
+It is important to note that you can also customise the parent TH and TD elements, customising both classes and attributes for each Column's header (using setThAttributes) and each row of that Column (using setTdAttributes), these are available in the configure() method of the table.
+This allows you to customise attributes based on the value of the table as well!
+
+Below is a copy of the relevant sections from [datatable styling](../datatable/styling) to ensure visibility of the options. More are documented on the main datatable styling page.
+
+## setThAttributes
+
+Set a list of attributes to override on the th elements.
+
+If your Column does not have a field (e.g. a label column), then you may use the following, which will utilise the first parameter in Column::make()
+```php
+ $column->getTitle()
+```
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column.
+ $this->setThAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'class' => 'bg-green-500',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+### Keeping Default Colors and Default Styling
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'default' => true,
+ 'class' => 'bg-green-500',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+### Keeping Default Styling Only For the "Name" Column
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'default' => false,
+ 'default-styling' => true,
+ 'class' => 'text-black bg-green-500 dark:text-white dark:bg-green-900',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+### Reorder Column
+Note: If you are using Reorder, then the th for Reorder can be [styled separately](../reordering/available-methods). However this is now replaced with the following to ensure consistent behaviour. The separate method will be supported until at least v3.6
+
+You can also use the "title" of the Column, which will be "reorder" for the "reorder" Column:
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->getTitle() == 'reorder')
+ {
+ return [
+ 'class' => 'bg-green-500 dark:bg-green-800',
+ 'default' => false,
+ 'default-colors' => false,
+ ];
+
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+### Bulk Actions Column
+Note: If you are using Bulk Actions, then the th for Bulk Actions can be [styled separately](../bulk-actions/customisations). However this is now replaced with the following to ensure consistent behaviour. The separate method will be supported until at least v3.6
+
+You can also use the "title" of the Column, which will be "bulkactions" for the "Bulk Actions" Column:
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->getTitle() == 'bulkactions')
+ {
+ return [
+ 'class' => 'bg-yellow-500 dark:bg-yellow-800',
+ 'default' => false,
+ 'default-colors' => false,
+ ];
+
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+## setThSortButtonAttributes
+
+Set a list of attributes to override on the th sort button elements
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column.
+ $this->setThSortButtonAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'class' => 'bg-green-500',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+## setTrAttributes
+
+Set a list of attributes to override on the tr elements
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current row and its index
+ $this->setTrAttributes(function($row, $index) {
+ if ($index % 2 === 0) {
+ return [
+ 'class' => 'bg-gray-200',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+By default, this replaces the default classes on the tr, if you would like to keep them, set the appropriate default flag (see above)
+
+```php
+public function configure(): void
+{
+ $this->setTrAttributes(function($row, $index) {
+ if ($index % 2 === 0) {
+ return [
+ 'default' => true,
+ 'class' => 'bg-gray-200',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+## setTdAttributes
+
+Set a list of attributes to override on the td elements. For example, changing the background color between red/green based on whether the "total" field is over or under 1000.
+
+If your Column does not have a field (e.g. a label column), then you may use the following, which will utilise the first parameter in Column::make()
+```php
+ $column->getTitle()
+```
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column, row, column index, and row index
+ $this->setTdAttributes(function(Column $column, $row, $columnIndex, $rowIndex) {
+ if ($column->isField('total') && $row->total < 1000) {
+ return [
+ 'class' => 'bg-red-500 text-white',
+ ];
+ }
+ elseif ($column->isField('total') && $row->total >= 1000) {
+ return [
+ 'class' => 'bg-green-500 text-white',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+By default, this replaces the default classes on the td, if you would like to keep them, set the appropriate default flag (see above).
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column, row, column index, and row index
+ $this->setTdAttributes(function(Column $column, $row, $columnIndex, $rowIndex) {
+ if ($column->isField('total') && $row->total < 1000) {
+ return [
+ 'default' => true,
+ 'class' => 'bg-red-500 text-white',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+
+```
+
+### Reorder Column
+Note: If you are using Reorder, then the td for Reorder can be [styled separately](../reordering/available-methods). However this is now replaced with the following to ensure consistent behaviour. The separate method will be supported until at least v3.6
+
+You can use the "title" of the Column, which will be "reorder" for the "reorder" Column:
+```php
+public function configure(): void
+{
+ $this->setTdAttributes(function(Column $column) {
+ if ($column->getTitle() == 'reorder')
+ {
+ return [
+ 'class' => 'bg-green-500 dark:bg-green-800',
+ 'default' => false,
+ 'default-colors' => false,
+ ];
+
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+### Bulk Actions Column
+Note: If you are using Bulk Actions, then the td for Bulk Actions can be [styled separately](../bulk-actions/customisations). However this is now replaced with the following to ensure consistent behaviour. The separate method will be supported until at least v3.6
+
+You can use the "title" of the Column, which will be "bulkactions" for the "Bulk Actions" Column:
+```php
+public function configure(): void
+{
+ $this->setTdAttributes(function(Column $column) {
+ if ($column->getTitle() == 'bulkactions')
+ {
+ return [
+ 'class' => 'bg-yellow-500 dark:bg-yellow-800',
+ 'default' => false,
+ 'default-colors' => false,
+ ];
+
+ }
+
+ return ['default' => true];
+ });
+}
+```
diff --git a/docs/datatable/available-methods.md b/docs/datatable/available-methods.md
index f774367f4..01023973e 100644
--- a/docs/datatable/available-methods.md
+++ b/docs/datatable/available-methods.md
@@ -18,285 +18,21 @@ public function configure(): void
}
```
-## Attributes
-
-### setComponentWrapperAttributes
-
-Set a list of attributes to override on the main wrapper of the component
-
-```php
-public function configure(): void
-{
- $this->setComponentWrapperAttributes([
- 'id' => 'my-id',
- 'class' => 'this that',
- ]);
-}
-```
-
-### setTableWrapperAttributes
-
-Set a list of attributes to override on the div that wraps the table
-
-```php
-public function configure(): void
-{
- $this->setTableWrapperAttributes([
- 'id' => 'my-id',
- 'class' => 'this that',
- ]);
-}
-```
-
-By default, this replaces the default classes on the table wrapper, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- $this->setTableWrapperAttributes([
- 'default' => true,
- 'class' => 'added these classes',
- ]);
-}
-```
-
-### setTableAttributes
-
-Set a list of attributes to override on the table element
-
-```php
-public function configure(): void
-{
- $this->setTableAttributes([
- 'id' => 'my-id',
- 'class' => 'this that',
- ]);
-}
-```
-
-By default, this replaces the default classes on the table, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- $this->setTableAttributes([
- 'default' => true,
- 'class' => 'added these classes',
- ]);
-}
-```
-
-### setTheadAttributes
-
-Set a list of attributes to override on the thead element
-
-```php
-public function configure(): void
-{
- $this->setTheadAttributes([
- 'id' => 'my-id',
- 'class' => 'this that',
- ]);
-}
-```
-
-By default, this replaces the default classes on the thead, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- $this->setTheadAttributes([
- 'default' => true,
- 'class' => 'added these classes',
- ]);
-}
-```
-
-### setTbodyAttributes
-
-Set a list of attributes to override on the tbody element
-
-```php
-public function configure(): void
-{
- $this->setTbodyAttributes([
- 'id' => 'my-id',
- 'class' => 'this that',
- ]);
-}
-```
-
-By default, this replaces the default classes on the tbody, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- $this->setTbodyAttributes([
- 'default' => true,
- 'class' => 'added these classes',
- ]);
-}
-```
-
-### setThAttributes
-
-Set a list of attributes to override on the th elements
-
-```php
-public function configure(): void
-{
- // Takes a callback that gives you the current column.
- $this->setThAttributes(function(Column $column) {
- if ($column->isField('name')) {
- return [
- 'class' => 'bg-green-500',
- ];
- }
-
- return [];
- });
-}
-```
+### useComputedPropertiesDisabled
-By default, this replaces the default classes on the th, if you would like to keep them, set the default flag to true.
+If you have published the Views **prior to v3.4.5**, and do not wish to remove the published views, then you should add the following call, which will disable the new Computed Properties behaviour. Note that publishing the views is not recommended!
```php
public function configure(): void
{
- $this->setThAttributes(function(Column $column) {
- if ($column->isField('name')) {
- return [
- 'default' => true,
- 'class' => 'bg-green-500',
- ];
- }
-
- return ['default' => true];
- });
+ $this->useComputedPropertiesDisabled();
}
```
-### setThSortButtonAttributes
-Set a list of attributes to override on the th sort button elements
-
-```php
-public function configure(): void
-{
- // Takes a callback that gives you the current column.
- $this->setThSortButtonAttributes(function(Column $column) {
- if ($column->isField('name')) {
- return [
- 'class' => 'bg-green-500',
- ];
- }
-
- return [];
- });
-}
-```
-
-### setTrAttributes
-
-Set a list of attributes to override on the tr elements
-
-```php
-public function configure(): void
-{
- // Takes a callback that gives you the current row and its index
- $this->setTrAttributes(function($row, $index) {
- if ($index % 2 === 0) {
- return [
- 'class' => 'bg-gray-200',
- ];
- }
-
- return [];
- });
-}
-```
-
-By default, this replaces the default classes on the tr, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- $this->setTrAttributes(function($row, $index) {
- if ($index % 2 === 0) {
- return [
- 'default' => true,
- 'class' => 'bg-gray-200',
- ];
- }
-
- return ['default' => true];
- });
-}
-```
-
-### setTdAttributes
-
-Set a list of attributes to override on the td elements
-
-```php
-public function configure(): void
-{
- // Takes a callback that gives you the current column, row, column index, and row index
- $this->setTdAttributes(function(Column $column, $row, $columnIndex, $rowIndex) {
- if ($column->isField('total') && $row->total < 1000) {
- return [
- 'class' => 'bg-red-500 text-white',
- ];
- }
-
- return [];
- });
-}
-```
-
-By default, this replaces the default classes on the td, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- // Takes a callback that gives you the current column, row, column index, and row index
- $this->setTdAttributes(function(Column $column, $row, $columnIndex, $rowIndex) {
- if ($column->isField('total') && $row->total < 1000) {
- return [
- 'default' => true,
- 'class' => 'bg-red-500 text-white',
- ];
- }
-
- return ['default' => true];
- });
-}
-
-```
-### setSearchFieldAttributes
-
-Set a list of attributes to override on the search field
-
-```php
-public function configure(): void
-{
- $this->setSearchFieldAttributes([
- 'class' => 'this that',
- ]);
-}
-```
+## Attributes
-By default, this replaces the default classes on the search field, if you would like to keep them, set the default flag to true.
-
-```php
-public function configure(): void
-{
- $this->setSearchFieldAttributes([
- 'default' => true,
- 'class' => 'added these classes',
- ]);
-}
-```
+Documentation for Data Table Styling/Attributes is now: [Here](../datatable/styling)
## Offline
@@ -340,43 +76,7 @@ public function configure(): void
## Query String
-The query string is **enabled by default**, but if you ever needed to toggle it you can use the following methods:
-
-### setQueryStringStatus
-
-Enable/disable the query string.
-
-```php
-public function configure(): void
-{
- $this->setQueryStringStatus(true);
- $this->setQueryStringStatus(false);
-}
-```
-
-### setQueryStringEnabled
-
-Enable the query string.
-
-```php
-public function configure(): void
-{
- // Shorthand for $this->setQueryStringStatus(true)
- $this->setQueryStringEnabled();
-}
-```
-
-### setQueryStringDisabled
-
-Disable the query string.
-
-```php
-public function configure(): void
-{
- // Shorthand for $this->setQueryStringStatus(false)
- $this->setQueryStringDisabled();
-}
-```
+The documentation for Query String now lives: [here](./query-string)
## Relationships
@@ -454,11 +154,11 @@ public function configure(): void
Set the message displayed when the table is filtered but there are no results to show.
-Defaults to: "_No items found. Try to broaden your search._"
+Defaults to: "_No items found, try to broaden your search._"
```php
public function configure(): void
{
$this->setEmptyMessage('No results found');
}
-```
+```
\ No newline at end of file
diff --git a/docs/datatable/configurable-areas.md b/docs/datatable/configurable-areas.md
index bb9d78a5b..489a42cd6 100644
--- a/docs/datatable/configurable-areas.md
+++ b/docs/datatable/configurable-areas.md
@@ -26,6 +26,7 @@ You can use the `setConfigurableAreas` method to set multiple areas that you wan
public function configure(): void
{
$this->setConfigurableAreas([
+ 'before-wrapper' => 'path.to.my.view',
'before-tools' => 'path.to.my.view',
'toolbar-left-start' => 'path.to.my.view',
'toolbar-left-end' => 'path.to.my.view',
@@ -33,8 +34,10 @@ public function configure(): void
'toolbar-right-end' => 'path.to.my.view',
'before-toolbar' => 'path.to.my.view',
'after-toolbar' => 'path.to.my.view',
+ 'after-tools' => 'path.to.my.view',
'before-pagination' => 'path.to.my.view',
'after-pagination' => 'path.to.my.view',
+ 'after-wrapper' => 'path.to.my.view',
]);
}
```
diff --git a/docs/datatable/events.md b/docs/datatable/events.md
index 69f52a104..dc81a5695 100644
--- a/docs/datatable/events.md
+++ b/docs/datatable/events.md
@@ -3,9 +3,10 @@ title: Events
weight: 2
---
-These are the available events on the datatable component that you can fire from your application:
+### Listened For
+These are the available events on the datatable component that you can fire from your application, or client-side
-### refreshDatatable
+#### refreshDatatable
```php
$this->dispatch('refreshDatatable');
@@ -13,7 +14,7 @@ $this->dispatch('refreshDatatable');
Calls `$refresh` on the component. Good for updating from external sources or as an alternative to polling.
-### setSort
+#### setSort
You can have the table sort a specific column:
@@ -21,7 +22,7 @@ You can have the table sort a specific column:
$this->dispatch('setSort', 'name', 'asc');
```
-### clearSorts
+#### clearSorts
You can clear all the applied sorts:
@@ -29,7 +30,7 @@ You can clear all the applied sorts:
$this->dispatch('clearSorts');
```
-### setFilter
+#### setFilter
You can have the table run a specific filter:
@@ -37,10 +38,111 @@ You can have the table run a specific filter:
$this->dispatch('setFilter', 'status', '1');
```
-### clearFilters
+#### clearFilters
You can have the table clear all filters:
```php
$this->dispatch('clearFilters');
```
+
+### Dispatched
+
+There are several events, all in the Rappasoft\LaravelLivewireTables\Events namespace
+| Event Name | Event Purpose | Data Passed |
+| --- | --- | --- |
+| ColumnsSelected | Applied whenever a Column is selected/deselected from view | The Table Name ($tableName), Selected Columns ($value), Logged In User ($user) |
+| FilterApplied | Applied when a Filter is applied (not when removed) | The Table Name ($tableName), Filter Key ($key), Filter Value ($value), Logged In User ($user) |
+| SearchApplied | Applied when a Search is applied (not when removed) | The Table Name ($tableName), Search Term ($value), Logged In User ($user) |
+
+Passing the user with an event is optional and [can be disabled in the config](../start/configuration.md#bypassing-laravels-auth-service).
+
+By default, the Tables will dispatch an event when the Selected Columns is changed, you may customise this behaviour:
+
+#### enableAllEvents
+
+This enables all Dispatched Events. This should be used with caution, as more events will be introduced in the future.
+
+```php
+public function configure(): void
+{
+ $this->enableAllEvents();
+}
+```
+
+#### disableAllEvents
+
+This disables all Dispatched Events.
+
+```php
+public function configure(): void
+{
+ $this->disableAllEvents();
+}
+```
+
+#### enableColumnSelectEvent
+
+Enables the Column Select Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+ $this->enableColumnSelectEvent();
+}
+```
+
+#### disableColumnSelectEvent
+
+Disables the Column Select Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+ $this->disableColumnSelectEvent();
+}
+```
+
+#### enableSearchAppliedEvent
+
+Enables the Search Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+ $this->enableSearchAppliedEvent();
+}
+```
+
+#### disableSearchAppliedEvent
+
+Disables the Search Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+ $this->disableSearchAppliedEvent();
+}
+```
+
+#### enableFilterAppliedEvent
+
+Enables the Filter Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+ $this->enableFilterAppliedEvent();
+}
+```
+
+#### disableFilterAppliedEvent
+
+Disables the Filter Applied Event, has no impact on other events
+
+```php
+public function configure(): void
+{
+ $this->disableFilterAppliedEvent();
+}
+```
diff --git a/docs/datatable/query-string.md b/docs/datatable/query-string.md
new file mode 100644
index 000000000..c830ef15a
--- /dev/null
+++ b/docs/datatable/query-string.md
@@ -0,0 +1,207 @@
+---
+title: Query String
+weight: 5
+---
+
+The query string is **enabled by default**, but if you ever needed to toggle it you can use the following methods:
+
+## Global
+### setQueryStringStatus
+
+Enable/disable the query string.
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringStatus(true);
+ $this->setQueryStringStatus(false);
+}
+```
+
+### setQueryStringEnabled
+
+Enable the query string.
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatus(true)
+ $this->setQueryStringEnabled();
+}
+```
+
+### setQueryStringDisabled
+
+Disable the query string.
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatus(false)
+ $this->setQueryStringDisabled();
+}
+```
+
+### setQueryStringAlias
+
+Change the Alias in the URL, otherwise defaults to "$tablename"
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringAlias('table1');
+}
+```
+
+## Filters
+
+The filter query string is **enabled by default**, but if you ever needed to toggle it you can use the following methods:
+
+### setQueryStringStatusForFilter
+
+Enable/disable the query string for the filters
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringStatusForFilter(true);
+ $this->setQueryStringStatusForFilter(false);
+}
+```
+
+### setQueryStringForFilterEnabled
+
+Enable the query string for the filters
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatusForFilter(true)
+ $this->setQueryStringForFilterEnabled();
+}
+```
+
+### setQueryStringForFilterDisabled
+
+Disable the query string for the filters
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatusForFilter(false)
+ $this->setQueryStringForFilterDisabled();
+}
+```
+
+### setQueryStringAliasForFilter
+
+Change the Alias in the URL for the filter, otherwise defaults to "$tablename-filters"
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringAliasForFilter('filtervalues');
+}
+```
+
+## Search
+
+The search query string is **enabled by default**, but if you ever needed to toggle it you can use the following methods:
+
+### setQueryStringStatusForSearch
+
+Enable/disable the query string for search
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringStatusForSearch(true);
+ $this->setQueryStringStatusForSearch(false);
+}
+```
+
+### setQueryStringForSearchEnabled
+
+Enable the query string for search
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatusForSearch(true)
+ $this->setQueryStringForSearchEnabled();
+}
+```
+
+### setQueryStringForSearchDisabled
+
+Disable the query string for search
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatusForSearch(false)
+ $this->setQueryStringForSearchDisabled();
+}
+```
+
+### setQueryStringAliasForSearch
+
+Change the Alias in the URL for the search, otherwise defaults to "$tablename-search"
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringAliasForSearch('search');
+}
+```
+
+## Sorts
+
+The sorts query string is **enabled by default**, but if you ever needed to toggle it you can use the following methods:
+
+### setQueryStringStatusForSort
+
+Enable/disable the query string for sort
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringStatusForSort(true);
+ $this->setQueryStringStatusForSort(false);
+}
+```
+
+### setQueryStringForSortEnabled
+
+Enable the query string for sort
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatusForSort(true)
+ $this->setQueryStringForSortEnabled();
+}
+```
+
+### setQueryStringForSortDisabled
+
+Disable the query string for sort
+
+```php
+public function configure(): void
+{
+ // Shorthand for $this->setQueryStringStatusForSort(false)
+ $this->setQueryStringForSortDisabled();
+}
+```
+
+### setQueryStringAliasForSort
+
+Change the Alias in the URL for the sorts, otherwise defaults to "$tablename-sorts"
+
+```php
+public function configure(): void
+{
+ $this->setQueryStringAliasForSort('sorts');
+}
+```
\ No newline at end of file
diff --git a/docs/datatable/styling.md b/docs/datatable/styling.md
new file mode 100644
index 000000000..937a6df94
--- /dev/null
+++ b/docs/datatable/styling.md
@@ -0,0 +1,499 @@
+---
+title: Styling
+weight: 6
+---
+
+The package offers significant opportunities to customise the look & feel of the core table, as well as other elements (which are documented in the relevant sections).
+
+## Keeping Defaults
+To allow simpler customisation on a per-table basis, there are numerous methods available to over-ride the default CSS classes.
+Historically, this was provided by a simple toggleable "default" flag. However - in many cases, the original "default" has been expanded to include:
+
+### Keep Default Colors And Default Styles
+- set default flag to true
+or
+- set default-colors flag to true
+- set default-styling flag to true
+
+### Keep Default Colors Only
+- set default flag to false
+- set default-colors flag to true
+- set default-styling flag to false
+
+### Keep Default Styling Only
+- set default flag to false
+- set default-colors flag to false
+- set default-styling flag to true
+
+
+## Attributes
+
+### setComponentWrapperAttributes
+
+Set a list of attributes to override on the main wrapper of the component
+
+```php
+public function configure(): void
+{
+ $this->setComponentWrapperAttributes([
+ 'id' => 'my-id',
+ 'class' => 'this that',
+ ]);
+}
+```
+
+### setTableWrapperAttributes
+
+Set a list of attributes to override on the div that wraps the table
+
+```php
+public function configure(): void
+{
+ $this->setTableWrapperAttributes([
+ 'id' => 'my-id',
+ 'class' => 'this that',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the table wrapper, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ $this->setTableWrapperAttributes([
+ 'default' => true,
+ 'class' => 'added these classes',
+ ]);
+}
+```
+
+### setTableAttributes
+
+Set a list of attributes to override on the table element
+
+```php
+public function configure(): void
+{
+ $this->setTableAttributes([
+ 'id' => 'my-id',
+ 'class' => 'this that',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the table, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ $this->setTableAttributes([
+ 'default' => true,
+ 'class' => 'added these classes',
+ ]);
+}
+```
+
+### setTheadAttributes
+
+Set a list of attributes to override on the thead element
+
+```php
+public function configure(): void
+{
+ $this->setTheadAttributes([
+ 'id' => 'my-id',
+ 'class' => 'this that',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the thead, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ $this->setTheadAttributes([
+ 'default' => true,
+ 'class' => 'added these classes',
+ ]);
+}
+```
+
+### setTbodyAttributes
+
+Set a list of attributes to override on the tbody element
+
+```php
+public function configure(): void
+{
+ $this->setTbodyAttributes([
+ 'id' => 'my-id',
+ 'class' => 'this that',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the tbody, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ $this->setTbodyAttributes([
+ 'default' => true,
+ 'class' => 'added these classes',
+ ]);
+}
+```
+
+### setThAttributes
+
+Set a list of attributes to override on the th elements.
+
+If your Column does not have a field (e.g. a label column), then you may use the following, which will utilise the first parameter in Column::make()
+```php
+ $column->getTitle()
+```
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column.
+ $this->setThAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'class' => 'bg-green-500',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+#### Keeping Default Colors and Default Styling
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'default' => true,
+ 'class' => 'bg-green-500',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+#### Keeping Default Styling Only For the "Name" Column
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'default' => false,
+ 'default-styling' => true,
+ 'class' => 'text-black bg-green-500 dark:text-white dark:bg-green-900',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+#### Reorder Column
+Note: If you are using Reorder, then the th for Reorder can be [styled separately](../reordering/available-methods). However this is now replaced with the following to ensure consistent behaviour. The separate method will be supported until at least v3.6
+
+You can also use the "title" of the Column, which will be "reorder" for the "reorder" Column:
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->getTitle() == 'reorder')
+ {
+ return [
+ 'class' => 'bg-green-500 dark:bg-green-800',
+ 'default' => false,
+ 'default-colors' => false,
+ ];
+
+ }
+
+ return ['default' => true];
+ });
+}
+```
+#### Bulk Actions Column
+Note: If you are using Bulk Actions, then the th for Bulk Actions can be [styled separately](../bulk-actions/customisations). However this is now replaced with the following to ensure consistent behaviour. The separate method will be supported until at least v3.6
+
+You can also use the "title" of the Column, which will be "bulkactions" for the "Bulk Actions" Column:
+```php
+public function configure(): void
+{
+ $this->setThAttributes(function(Column $column) {
+ if ($column->getTitle() == 'bulkactions')
+ {
+ return [
+ 'class' => 'bg-yellow-500 dark:bg-yellow-800',
+ 'default' => false,
+ 'default-colors' => false,
+ ];
+
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+
+
+
+### setThSortButtonAttributes
+
+Set a list of attributes to override on the th sort button elements
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column.
+ $this->setThSortButtonAttributes(function(Column $column) {
+ if ($column->isField('name')) {
+ return [
+ 'class' => 'bg-green-500',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+### setTrAttributes
+
+Set a list of attributes to override on the tr elements
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current row and its index
+ $this->setTrAttributes(function($row, $index) {
+ if ($index % 2 === 0) {
+ return [
+ 'class' => 'bg-gray-200',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+By default, this replaces the default classes on the tr, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ $this->setTrAttributes(function($row, $index) {
+ if ($index % 2 === 0) {
+ return [
+ 'default' => true,
+ 'class' => 'bg-gray-200',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+```
+
+### setTdAttributes
+
+Set a list of attributes to override on the td elements
+
+If your Column does not have a field (e.g. a label column), then you may use the following, which will utilise the first parameter in Column::make()
+```php
+ $column->getTitle()
+```
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column, row, column index, and row index
+ $this->setTdAttributes(function(Column $column, $row, $columnIndex, $rowIndex) {
+ if ($column->isField('total') && $row->total < 1000) {
+ return [
+ 'class' => 'bg-red-500 text-white',
+ ];
+ }
+
+ return [];
+ });
+}
+```
+
+By default, this replaces the default classes on the td, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ // Takes a callback that gives you the current column, row, column index, and row index
+ $this->setTdAttributes(function(Column $column, $row, $columnIndex, $rowIndex) {
+ if ($column->isField('total') && $row->total < 1000) {
+ return [
+ 'default' => true,
+ 'class' => 'bg-red-500 text-white',
+ ];
+ }
+
+ return ['default' => true];
+ });
+}
+
+```
+### setSearchFieldAttributes
+
+Set a list of attributes to override on the search field
+
+```php
+public function configure(): void
+{
+ $this->setSearchFieldAttributes([
+ 'class' => 'this that',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the search field, if you would like to keep them, set the default flag to true.
+
+```php
+public function configure(): void
+{
+ $this->setSearchFieldAttributes([
+ 'default' => true,
+ 'class' => 'added these classes',
+ ]);
+}
+```
+
+### setCollapsingColumnButtonCollapseAttributes
+
+This customises the look & feel of the button displayed to Collapse an expanded Collapsed Column
+
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonCollapseAttributes([
+ 'class' => 'text-blue-500',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the button, if you would like to keep:
+Default Colors: set default-colors flag to true.
+Default Styling: set default-styling flag to true.
+
+#### Keeping the Default Styling
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonCollapseAttributes([
+ 'default-styling' => true,
+ 'class' => 'text-blue-500',
+ ]);
+}
+```
+
+#### Keeping the Default Colors
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonCollapseAttributes([
+ 'default-colors' => true,
+ 'class' => 'h-12 w-12',
+ ]);
+}
+```
+
+#### Replacing All
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonCollapseAttributes([
+ 'class' => 'h-12 w-12 text-blue-500',
+ ]);
+}
+```
+
+
+### setCollapsingColumnButtonExpandAttributes
+
+This customises the look & feel of the button displayed to Expand a collapsed Collapsed Column
+
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonExpandAttributes([
+ 'class' => 'text-red-500',
+ ]);
+}
+```
+
+By default, this replaces the default classes on the button, if you would like to keep:
+Default Colors: set default-colors flag to true.
+Default Styling: set default-styling flag to true.
+
+#### Keeping the Default Styling
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonExpandAttributes([
+ 'default-styling' => true,
+ 'class' => 'text-red-500',
+ ]);
+}
+```
+
+#### Keeping the Default Colors
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonExpandAttributes([
+ 'default-colors' => true,
+ 'class' => 'h-12 w-12',
+ ]);
+}
+```
+
+#### Replacing All
+```php
+public function configure(): void
+{
+ $this->setCollapsingColumnButtonExpandAttributes([
+ 'class' => 'h-12 w-12 text-red-500',
+ ]);
+}
+```
+
+### Vertical Scrolling Example
+Should you wish to implement a table with a responsive height, and vertical scrolling for additional rows, a basic example is below that demonstrates the approach, noting that you will likely wish to adjust the break-points!
+
+```php
+public function configure(): void
+{
+
+ $this->setTableWrapperAttributes([
+ 'class' => 'max-h-56 md:max-h-72 lg:max-h-96 overflow-y-scroll',
+ ]);
+ $this->setTheadAttributes([
+ 'class' => 'sticky top-0 '
+ ]);
+}
+```
+
+Keep in mind that you must only call methods from configure() once to avoid overriding or conflicting results.
\ No newline at end of file
diff --git a/docs/examples/_index.md b/docs/examples/_index.md
index a831d1a26..03b1d982b 100644
--- a/docs/examples/_index.md
+++ b/docs/examples/_index.md
@@ -1,4 +1,4 @@
---
title: Examples
-weight: 14
+weight: 16
---
diff --git a/docs/filter-types/_index.md b/docs/filter-types/_index.md
index 6c6d8ccf4..3631183ba 100644
--- a/docs/filter-types/_index.md
+++ b/docs/filter-types/_index.md
@@ -1,4 +1,4 @@
---
title: Filter Types
-weight: 11
+weight: 12
---
diff --git a/docs/filter-types/filters-boolean.md b/docs/filter-types/filters-boolean.md
new file mode 100644
index 000000000..e73343afd
--- /dev/null
+++ b/docs/filter-types/filters-boolean.md
@@ -0,0 +1,39 @@
+---
+title: Boolean Filters (beta)
+weight: 2
+---
+
+## Beta
+This is currently in beta, but should work with Tailwind, Bootstrap 4 and Bootstrap 5 as of latest version
+
+## Details
+
+The BooleanFilter is designed so that you can toggle a more complex query/filter, as opposed to being a yes/no type of filter (which is what the SelectFilter is perfect for)
+
+For example, your filter may look like this, toggling the filter from true to false would apply/not apply a more complex query to the query.
+
+```php
+ BooleanFilter::make('Limit to Older Enabled Users')
+ ->filter(function (Builder $builder, bool $enabled) {
+ if ($enabled)
+ {
+ $builder->where('status',true)->where('age', '>', 60);
+ }
+ })
+```
+
+Many of the standard methods are available, for example
+```php
+ BooleanFilter::make('Limit to Older Enabled Users')
+ ->filter(function (Builder $builder, bool $enabled) {
+ if ($enabled)
+ {
+ $builder->where('status',true)->where('age', '>', 60);
+ }
+ })
+ ->setFilterPillValues([
+ true => 'Active',
+ false => 'Inactive',
+ ])
+ ->setFilterDefaultValue(true)
+```
\ No newline at end of file
diff --git a/docs/filter-types/filters-date.md b/docs/filter-types/filters-date.md
index 488cda84f..f59cda5d4 100644
--- a/docs/filter-types/filters-date.md
+++ b/docs/filter-types/filters-date.md
@@ -1,10 +1,8 @@
---
title: Date Filters
-weight: 2
+weight: 3
---
-## Date Filters
-
Date filters are HTML date elements.
```php
@@ -35,6 +33,7 @@ public function filters(): array
}
```
+## setFilterDefaultValue
Date filters also support the setFilterDefaultValue() method, which must be a valid date in the "Y-m-d" format. This will apply as a default until removed.
```php
public function filters(): array
@@ -49,5 +48,22 @@ public function filters(): array
];
}
```
-
+
+## setPillsLocale
+Date Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values
+```php
+public function filters(): array
+{
+ return [
+ DateFilter::make('Verified From')
+ ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
+ ->config([
+ 'min' => '2020-01-01', // Earliest Acceptable Date
+ 'max' => '2021-12-31', // Latest Acceptable Date
+ 'pillFormat' => 'd M Y', // Format for use in Filter Pills
+ 'placeholder' => 'Enter Date', // A placeholder value
+ ])
+ ];
+}
+```
diff --git a/docs/filter-types/filters-daterange.md b/docs/filter-types/filters-daterange.md
index 37d0ea552..71241daba 100644
--- a/docs/filter-types/filters-daterange.md
+++ b/docs/filter-types/filters-daterange.md
@@ -1,10 +1,8 @@
---
title: DateRange Filters
-weight: 3
+weight: 4
---
-## DateRange Filters
-
DateRange filters are Flatpickr based components, and simply filtering by a date range. If you would like to more smoothly filter your query by a start and end date, you can use the DateRangeFilter:
```php
@@ -33,6 +31,7 @@ public function filters(): array
'earliestDate' => '2020-01-01', // The earliest acceptable date
'latestDate' => '2023-08-01', // The latest acceptable date
'placeholder' => 'Enter Date Range', // A placeholder value
+ 'locale' => 'en',
])
->setFilterPillValues([0 => 'minDate', 1 => 'maxDate']) // The values that will be displayed for the Min/Max Date Values
->filter(function (Builder $builder, array $dateRange) { // Expects an array.
@@ -44,31 +43,156 @@ public function filters(): array
}
```
+A full list of options is below, please see the Flatpickr documentation for reference as to purpose:
+| Config Option | Type | Default | Description |
+| ------------- | ------------- | ------------- | ------------- |
+| allowInvalidPreload | Boolean | true | Allows the preloading of an invalid date. When disabled, the field will be cleared if the provided date is invalid |
+| allowInput | Boolean | false | Allows the user to enter a date directly into the input field. By default, direct entry is disabled. |
+| altFormat | String | "F j, Y" | Exactly the same as date format, but for the altInput field |
+| altInput | Boolean | false | Show the user a readable date (as per altFormat), but return something totally different to the server. |
+| ariaDateFormat | String | "F j, Y" | Defines how the date will be formatted in the aria-label for calendar days, using the same tokens as dateFormat. If you change this, you should choose a value that will make sense if a screen reader reads it out loud. |
+| dateFormat | String | 'Y-m-d' | A string of characters which are used to define how the date will be displayed in the input box |
+| defaultDate | String | null | Sets the initial selected date |
+| defaultHour | Number | 12 | Initial value of the hour element. |
+| defaultMinute | Number | 0 | Initial value of the minute element. |
+| earliestDate | String/Date | null | The minimum date that a user can start picking from (inclusive) |
+| enableTime | Boolean | false | Enables time picker |
+| enableSeconds | Boolean | false | Enables seconds in the time picker. |
+| hourIncrement | Integer | 1 | Adjusts the step for the hour input (incl. scrolling) |
+| latestDate | String/Date | null | The maximum date that a user can pick to (inclusive) |
+| locale | String | en | The locale used (see below) |
+| minuteIncrement | Integer | 5 | Adjusts the step for the minute input (incl. scrolling) |
+| placeholder | String | null | Set a placeholder value for the input field |
+| shorthandCurrentMonth | Boolean | false | Show the month using the shorthand version (ie, Sep instead of September). |
+| time_24hr | Boolean | false | Displays time picker in 24 hour mode without AM/PM selection when enabled. |
+| weekNumbers | Boolean | false | Enables display of week numbers in calendar. |
+
+## setFilterDefaultValue
+You may use this to set a default value for the filter that will be applied on first load (but may be cleared by the user). This should be an array:
+
+```php
+ DateRangeFilter::make('EMail Verified Range')
+ ->setFilterDefaultValue(['minDate' => '2024-05-05', 'maxDate' => '2024-06-06'])
+```
+or
+```php
+ DateRangeFilter::make('EMail Verified Range')
+ ->setFilterDefaultValue(['min' => '2024-05-05', 'max' => '2024-06-06'])
+```
+or
+```php
+ DateRangeFilter::make('EMail Verified Range')
+ ->setFilterDefaultValue(['2024-05-05', '2024-06-06'])
+```
+
+## setPillsLocale
+DateRange Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values
+```php
+public function filters(): array
+{
+ return [
+ DateRangeFilter::make('EMail Verified Range')
+ ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
+ ->config([
+ 'allowInput' => true, // Allow manual input of dates
+ 'altFormat' => 'F j, Y', // Date format that will be displayed once selected
+ 'ariaDateFormat' => 'F j, Y', // An aria-friendly date format
+ 'dateFormat' => 'Y-m-d', // Date format that will be received by the filter
+ 'earliestDate' => '2020-01-01', // The earliest acceptable date
+ 'latestDate' => '2023-08-01', // The latest acceptable date
+ 'placeholder' => 'Enter Date Range', // A placeholder value
+ 'locale' => 'en',
+ ])
+ ->setFilterPillValues([0 => 'minDate', 1 => 'maxDate']) // The values that will be displayed for the Min/Max Date Values
+ ->filter(function (Builder $builder, array $dateRange) { // Expects an array.
+ $builder
+ ->whereDate('users.email_verified_at', '>=', $dateRange['minDate']) // minDate is the start date selected
+ ->whereDate('users.email_verified_at', '<=', $dateRange['maxDate']); // maxDate is the end date selected
+ }),
+ ];
+}
+```
## Configuration
-By default, this filter will use a CDN to include the Flatpickr JS Library and CSS. However, you can customise this behaviour using the configuration file.
+By default, this filter will inject the Flatpickr JS Library and CSS. However, you can customise this behaviour using the configuration file.
-### Option 1 - The default CDN behaviour:
+### Option 1 - The default behaviour:
+```php
+ 'inject_third_party_assets_enabled' => true,
```
- 'published_third_party_assets' => false,
- 'remote_third_party_assets' => true,
+
+### Option 2 - Bundled
+If you choose to bundle the Tables JS/CSS (recommended) by adding the following to your build process:
+
+```js
+'vendor/rappasoft/laravel-livewire-tables/resources/js/laravel-livewire-tables-thirdparty.min.js';
```
-### Option 2 - Publish included version
-You may publish the included version of Flatpickr. To do so, run:
+or in your app.js
+
+```js
+import '../../vendor/rappasoft/livewire-tables/resources/js/laravel-livewire-tables-thirdparty.min.js';
```
-php artisan vendor:publish --tag=livewire-tables-public
+
+Then you should disable injection to avoid conflicts:
+
+```php
+ 'inject_third_party_assets_enabled' => false,
```
-This will publish the tested version of Flatpickr to your public directory. You should then set
+
+### Option 3 - CDN
+You must ensure that Flatpickr is present PRIOR to the tables loading. For example, to add Flatpickr with the Spanish locale, ensure that the following is present in your Layout head section. Noting the "async" presence to ensure that the script is present before a page renders.
+
+It is typically recommended not to utilise the CDN approach, as changes to core code may impact behaviour, and you may need to implement changes to your CSP if present.
+
+If using the CDN approach, ensure the following config matches:
+```js
+ 'inject_third_party_assets_enabled' => false,
```
- 'published_third_party_assets' => true,
- 'remote_third_party_assets' => false,
+
+Then include the following in your layout:
+```html
+// Flatpickr Core Script
+
+
+// Flatpickr Core CSS
+
```
-### Option 3 - Locally Installed
-If you have a locally installed version of Flatpickr already, you can set both options to false, and your local version will be used instead.
+### Option 4 - Locally Installed
+If you have a locally installed version of Flatpickr already, you can set injection to false, and your local version will be used instead.
+```js
+ 'inject_third_party_assets_enabled' => false,
```
- 'published_third_party_assets' => false,
- 'remote_third_party_assets' => false,
+
+## Localisation (BETA)
+The default installation includes only the English (en) locale.
+
+### Bundling
+Should you wish to localise, you must include the Flatpickr locale files in your build pipeline. This applies to only the specific locales that you require in your app.js (requires adding the flatpickr library to your package.json by executing "npm i flatpickr --save")
+```js
+import { Arabic } from "../imports/flatpickr/l10n/ar.js";
+import { Catalan } from "../imports/flatpickr/l10n/cat.js";
+import { Danish } from "../imports/flatpickr/l10n/da.js";
+import { German } from "../imports/flatpickr/l10n/de.js";
+import { Spanish } from "../imports/flatpickr/l10n/es.js";
+import { French } from "../imports/flatpickr/l10n/fr.js";
+import { Indonesian } from "../imports/flatpickr/l10n/id.js";
+import { Italian } from "../imports/flatpickr/l10n/it.js";
+import { Malaysian } from "../imports/flatpickr/l10n/ms.js";
+import { Dutch } from "../imports/flatpickr/l10n/nl.js";
+import { Portuguese } from "../imports/flatpickr/l10n/pt.js";
+import { Russian } from "../imports/flatpickr/l10n/ru.js"
+import { Thai } from "../imports/flatpickr/l10n/th.js"
+import { Turkish } from "../imports/flatpickr/l10n/tr.js"
+import { Ukrainian } from "../imports/flatpickr/l10n/uk.js"
```
+
+### CDN
+You can also add locales using the Flatpickr CDN, ensuring that these are loaded before the page renders.
+
+For example to add German (de), ensure that the following is in the "head" section of your layout, ideally before your app.js
+```html
+
+```
\ No newline at end of file
diff --git a/docs/filter-types/filters-datetime.md b/docs/filter-types/filters-datetime.md
index 288d90b4b..cceef28d5 100644
--- a/docs/filter-types/filters-datetime.md
+++ b/docs/filter-types/filters-datetime.md
@@ -1,10 +1,8 @@
---
title: DateTime Filters
-weight: 4
+weight: 5
---
-## DateTime Filters
-
DateTime filters are HTML datetime-local elements and act the same as date filters.
```php
@@ -35,6 +33,7 @@ public function filters(): array
}
```
+## setFilterDefaultValue
DateTime filters also support the setFilterDefaultValue() method, which must be a valid datetime in the "Y-m-dTH:i" format. This will apply as a default until removed.
```php
public function filters(): array
@@ -49,6 +48,23 @@ public function filters(): array
->setFilterDefaultValue('2023-07-07T06:27')
];
}
+```
+
+## setPillsLocale
+DateTime Filters also support the setPillsLocale method, which allows you to set a locale for use in generating the Filter Pills values
+```php
+public function filters(): array
+{
+ return [
+ DateTimeFilter::make('Verified From')
+ ->setPillsLocale('fr ') // Use French localisation for the Filter Pills values
+ ->config([
+ 'min' => '2020-01-01', // Earliest Acceptable Date
+ 'max' => '2021-12-31', // Latest Acceptable Date
+ 'pillFormat' => 'd M Y - H:i', // Format for use in Filter Pills
+ 'placeholder' => 'Enter Date', // A placeholder value
+ ])
+ ];
+}
```
-
diff --git a/docs/filter-types/filters-livewire-component-array.md b/docs/filter-types/filters-livewire-component-array.md
new file mode 100644
index 000000000..86b2491dc
--- /dev/null
+++ b/docs/filter-types/filters-livewire-component-array.md
@@ -0,0 +1,51 @@
+---
+title: Livewire Custom Array Filter (Beta)
+weight: 13
+---
+
+**IN BETA**
+This feature is currently in beta, and use in production is not recommended.
+
+### Usage
+This allows you to use a child/nested Livewire Component in place of the existing Filters, giving you more control over the look/feel/behaviour of a filter. This version supports use of returning an array of values for use in filtering.
+
+To use a LivewireComponentArrayFilter, you must include it in your namespace:
+```php
+use Rappasoft\LaravelLivewireTables\Views\Filters\LivewireComponentArrayFilter;
+```
+
+When creating a filter:
+- Specify a unique name
+- Set the path to a valid Livewire Component
+- Define a filter() callback to define how the returned value will be used.
+
+```php
+ public function filters(): array
+ {
+ return [
+ LivewireComponentArrayFilter::make('My External Filter')
+ ->setLivewireComponent('my-test-external-filter')
+ ->filter(function (Builder $builder, array $values) {
+ $builder->whereIn('foreign_id', $values);
+ }),
+ ];
+ }
+```
+
+### setPillsSeparator
+As this is an array, you can define the separator to use between pills values, by default this is set to ", "
+
+```php
+ public function filters(): array
+ {
+ return [
+ LivewireComponentArrayFilter::make('My External Filter')
+ ->setLivewireComponent('my-test-external-filter')
+ ->setPillsSeparator(' OR ')
+ ->filter(function (Builder $builder, array $values) {
+ $builder->whereIn('foreign_id', $values);
+ }),
+ ];
+ }
+```
+
diff --git a/docs/filter-types/filters-livewire-component.md b/docs/filter-types/filters-livewire-component.md
index d11d337f9..7d5e3b7ae 100644
--- a/docs/filter-types/filters-livewire-component.md
+++ b/docs/filter-types/filters-livewire-component.md
@@ -1,10 +1,8 @@
---
title: Livewire Custom Filter (Beta)
-weight: 11
+weight: 12
---
-## Livewire Custom Filter
-
**IN BETA**
This feature is currently in beta, and use in production is not recommended.
diff --git a/docs/filter-types/filters-multiselect-dropdown.md b/docs/filter-types/filters-multiselect-dropdown.md
index d81c14570..8b4158975 100644
--- a/docs/filter-types/filters-multiselect-dropdown.md
+++ b/docs/filter-types/filters-multiselect-dropdown.md
@@ -1,11 +1,8 @@
---
title: Multi-Select Dropdown Filters
-weight: 5
+weight: 6
---
-
-## Multi-select dropdown Filters
-
Multi-select dropdown filters are a simple dropdown list. The user can select multiple options from the list. There is also an 'All' option that will select all values
```php
@@ -27,3 +24,26 @@ public function filters(): array
];
}
```
+
+## Filter Pills Separator
+
+As this filter returns one or more values, you have the option to utilise a custom separator for the values displayed in the Filter Pills section at the top of the table. The default is ", ", but you may use any HTML string to separate the selected values
+
+```php
+public function filters(): array
+{
+ return [
+ MultiSelectFilter::make('Tags')
+ ->options(
+ Tag::query()
+ ->orderBy('name')
+ ->get()
+ ->keyBy('id')
+ ->map(fn($tag) => $tag->name)
+ ->toArray()
+ )
+ ->setPillsSeparator(' '),
+ ];
+}
+
+```
\ No newline at end of file
diff --git a/docs/filter-types/filters-multiselect.md b/docs/filter-types/filters-multiselect.md
index f6c6bfa37..8535e8fef 100644
--- a/docs/filter-types/filters-multiselect.md
+++ b/docs/filter-types/filters-multiselect.md
@@ -1,10 +1,8 @@
---
title: Multi-Select Filters
-weight: 6
+weight: 7
---
-## Multi-select Filters
-
Multi-select filters are a list of checkboxes. The user can select multiple options from the list. There is also an 'All' option that will select all values.
```php
@@ -25,3 +23,26 @@ public function filters(): array
];
}
```
+
+## Filter Pills Separator
+
+As this filter returns one or more values, you have the option to utilise a custom separator for the values displayed in the Filter Pills section at the top of the table. The default is ", ", but you may use any HTML string to separate the selected values
+
+```php
+public function filters(): array
+{
+ return [
+ MultiSelectFilter::make('Tags')
+ ->options(
+ Tag::query()
+ ->orderBy('name')
+ ->get()
+ ->keyBy('id')
+ ->map(fn($tag) => $tag->name)
+ ->toArray()
+ )
+ ->setPillsSeparator(' '),
+ ];
+}
+
+```
\ No newline at end of file
diff --git a/docs/filter-types/filters-number-range.md b/docs/filter-types/filters-number-range.md
index 0969e5c33..d051bfd99 100644
--- a/docs/filter-types/filters-number-range.md
+++ b/docs/filter-types/filters-number-range.md
@@ -1,10 +1,8 @@
---
title: NumberRange Filters
-weight: 7
+weight: 8
---
-## NumberRange Filters
-
NumberRange filters allow for a minimum and maximum value to be input on a single slider.
```php
@@ -22,6 +20,7 @@ public function filters(): array
'minRange' => 0,
'maxRange' => 100,
'suffix' => '%',
+ 'prefix' => '$',
])
->filter(function (Builder $builder, array $values) {
$builder->where('users.success_rate', '>=', intval($values['min']))
@@ -34,4 +33,6 @@ public function filters(): array
The default values should be set in the options() method.
-You may also specify a minimum and maximum range in the config() options, and should you wish to use real values instead of a percentage, you can change the "suffix" to a metric of your choosing.
+You may also specify a minimum and maximum range in the config() options, and should you wish to use real values instead of a percentage.
+You can change the "suffix" to a metric of your choosing.
+You can change the "prefix" to an item of your choosing (e.g $/£/€)
diff --git a/docs/filter-types/filters-number.md b/docs/filter-types/filters-number.md
index 3b629dd0a..78dd191a3 100644
--- a/docs/filter-types/filters-number.md
+++ b/docs/filter-types/filters-number.md
@@ -1,12 +1,31 @@
---
title: Number Filters
-weight: 8
+weight: 9
---
-## Number Filters
-
Number filters are just HTML number inputs.
+```php
+public function filters(): array
+{
+ return [
+ NumberFilter::make('Amount')
+ ->filter(function(Builder $builder, string $value) {
+ $builder->where('amount', '<', $value);
+ }),
+ ];
+}
+```
+
+Historically, min/max/placeholders were set using the "config" option, which is still available. However, it is strongly recommended to use the new setInputAttributes for enhanced customisation.
+
+## Old Behaviour
+The following would:
+- Set a min of 0
+- Set a max of 100
+- Add a placeholder
+- Keep the default colors & styling
+
```php
public function filters(): array
{
@@ -23,3 +42,28 @@ public function filters(): array
];
}
```
+
+## New Behaviour
+The following would:
+- Set a min of 5
+- Set a max of 20
+- Set steps to be 0.5
+- Add a placeholder
+- Keep the default colors & styling
+
+```php
+public function filters(): array
+{
+ return [
+ NumberFilter::make('Age')
+ ->setInputAttributes([
+ 'min' => '5', // Minimum Value Accepted
+ 'max' => '20', // Maximum Value Accepted
+ 'step' => '0.5', // Set step
+ 'placeholder' => 'Enter Number 0 - 100', // A placeholder value
+ 'default-colors' => true,
+ 'default-styling' => true,
+ ]),
+ ];
+}
+```
\ No newline at end of file
diff --git a/docs/filter-types/filters-select.md b/docs/filter-types/filters-select.md
index d28cfba94..d0b67a48c 100644
--- a/docs/filter-types/filters-select.md
+++ b/docs/filter-types/filters-select.md
@@ -1,10 +1,8 @@
---
title: Select Filters
-weight: 9
+weight: 10
---
-## Select Filters
-
Select filters are a simple dropdown list. The user selects one choice from the list.
```php
@@ -56,6 +54,6 @@ public function filters(): array
}
```
To set a default "All" option at the start of the dropdown, you can do so by utilising the
-```
+```php
->setFirstOption('NAME')
```
diff --git a/docs/filter-types/filters-text.md b/docs/filter-types/filters-text.md
index 649384915..d6affde29 100644
--- a/docs/filter-types/filters-text.md
+++ b/docs/filter-types/filters-text.md
@@ -1,11 +1,9 @@
---
title: Text Filters
-weight: 10
+weight: 11
---
-## Text Filters
-
-Text filters are just HTML text fields.
+Text filters are just simple text filters, allowing you to pass a string value into a builder query.
```php
public function filters(): array
@@ -22,3 +20,133 @@ public function filters(): array
];
}
```
+
+### Extra Helpers
+
+There are a number of helpers to simplify your code, should you not wish to rewrite the filter function repeatedly for a Text Filter. You can only use one of the below methods per-filter.
+
+#### Contains
+
+This executes the filter and returns results where the field contains the filter value
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->contains('users.name'),
+ ];
+}
+```
+
+#### notContains
+
+This executes the filter and returns results where the field does not contain filter value
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->notContains('users.name'),
+ ];
+}
+```
+
+#### startsWith
+
+This executes the filter and returns results where the field starts with the filter value
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->startsWith('users.name'),
+ ];
+}
+```
+
+#### notStartsWith
+
+This executes the filter and returns results where the field does not start with the filter value
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->notStartsWith('users.name'),
+ ];
+}
+```
+
+#### endsWith
+
+This executes the filter and returns results where the field ends with the filter value
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->endsWith('users.name'),
+ ];
+}
+```
+
+#### notEndsWith
+
+This executes the filter and returns results where the field does not end with the filter value
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->notEndsWith('users.name'),
+ ];
+}
+```
+
+#### setFieldName
+An optional method for setting the field to use when filtering, if used, you may omit the field from the above methods, for example:
+
+```php
+public function filters(): array
+{
+ return [
+ TextFilter::make('Name')
+ ->config([
+ 'placeholder' => 'Search Name',
+ 'maxlength' => '25',
+ ])
+ ->setFieldName('users.name')
+ ->contains(),
+ ];
+}
+```
diff --git a/docs/filter-types/introduction.md b/docs/filter-types/introduction.md
index d509cdc39..0e4d099cc 100644
--- a/docs/filter-types/introduction.md
+++ b/docs/filter-types/introduction.md
@@ -4,3 +4,39 @@ weight: 1
---
There are several Filter types available for use, offering a range of capabilities to filter your data.
+
+