You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -26,10 +27,10 @@ Laravel package to create beautiful common views like tables using only PHP code
26
27
-[Roadmap](#roadmap)
27
28
28
29
# Version compatibility
29
-
|Laravel views|Livewire|Laravel|
30
-
|-|-|-|
31
-
|2.x|2.x|7.x, 8.x|
32
-
|1.x|1.x|5.x, 6.x|
30
+
|Laravel views|Alpine|Livewire|Laravel|
31
+
|-|-|-|-|
32
+
|2.x|2.8.x, 3.x.x|2.x|7.x, 8.x|
33
+
|1.x|2.8.x|1.x|5.x, 6.x|
33
34
34
35
# Installation and basic usage
35
36
@@ -59,12 +60,13 @@ Add the following Blade directives in the *head* tag, and before the end *body*
59
60
</html>
60
61
```
61
62
62
-
These blade directives are also including [Laravel livewire](https://laravel-livewire.com/) and [Tailwindcss](https://tailwindcss.com/) styles and scripts, after that you may need to clear the view cache
63
+
Laravel Views includes by default a set up using different parts of the TALL stack assets like the [Laravel livewire](https://laravel-livewire.com/) and [Tailwindcss](https://tailwindcss.com/) styles and scripts, it alsoincludes the [Alpine.js](https://laravel-livewire.com/docs/2.x/alpine-js) script, after adding these directives you may need to clear the view cache
64
+
63
65
```bash
64
66
php artisan view:clear
65
67
```
66
-
If you are already using your own Tailwindcss setup you can set `laravel-views` to not importing Tailwindcss by default. ([Importing assets](./doc/laravel-views#including-assets))
67
68
69
+
These directives are fine for a dev environment, however, if you want to use your own Tailwindcss or Alpinde.js setup, you can [disable these assets](./doc/laravel-views#including-assets) from being loaded with the Laravel views directive.
68
70
# First table view
69
71
This is a basic usage of a table view, you can [read the full table view documentation ](doc/table-view.md)
With this artisan command a UsersTableView.php file will be created inside the `app/Http/Livewire` directory.
77
79
78
-
The basic usage needs a data repository (Eloquent query), headers and rows, you can customize the items to be shown, and the headers and data for each row like this example
80
+
The basic usage needs a model class, headers and rows, you can customize the items to be shown, and the headers and data for each row like this example
79
81
```php
80
82
<?php
81
83
@@ -87,10 +89,7 @@ use App\User;
87
89
88
90
class UsersTableView extends TableView
89
91
{
90
-
public function repository(): Builder
91
-
{
92
-
return User::query();
93
-
}
92
+
protected $model = User::class;
94
93
95
94
public function headers(): array
96
95
{
@@ -128,7 +127,7 @@ You could also use the `@livewire` blade directive.
128
127
129
128
At this point, you would be able to see a table with some data, the table view doesn't have any styled container or title as the image example, you can render the table view inside any container you want.
130
129
131
-
In the example above the view is using the User model created by default in every Laravel project, feel free to use any model you have, the method `row` is receiving a sinlge model object and you can use any property or public method you have difined inside your model.
130
+
In the example above the view is using the User model created by default in every Laravel project, feel free to use any model you want, the method `row` is receiving a sinlge model object and you can use any property or public method you have difined inside your model.
132
131
133
132
This is the basic usage of the table view, but you can customize it with more features.
134
133
@@ -177,4 +176,57 @@ Here's the plan for what's coming:
177
176
- Add tooltips to actions buttons
178
177
- Add a download action
179
178
- Add translations
180
-
- Add links as a UI helpers
179
+
- Add links as a UI helpers
180
+
181
+
## Upgrade guide
182
+
### From 2.2 to 2.3
183
+
**Cached views**
184
+
185
+
The blade directives have changed, you need to clear the cached views with `php artisan view:clear`
186
+
187
+
**Public assets**
188
+
189
+
The main assets (JS and CSS files) have changed, you need to publish the public assets again with `php artisan vendor:publish --tag=public --provider='LaravelViews\LaravelViewsServiceProvider' --force`
190
+
191
+
**Publish blade componentes**
192
+
193
+
Some of the internal components have changed, if you have published these components before to customize them, you will not have them up to date, unfourtunately you need to publish them again with `php artisan vendor:publish --tag=views --provider='LaravelViews\LaravelViewsServiceProvider'` and customize them as you need.
194
+
195
+
**Method `renderIf()` in actions**
196
+
197
+
Update the renderIf() function in your action classes adding a new `$view` parameter as follows:
198
+
```php
199
+
<?php
200
+
201
+
namespace App\Actions;
202
+
203
+
use LaravelViews\Actions\Action;
204
+
use LaravelViews\Views\View; // new line
205
+
206
+
class YourAction extends Action
207
+
{
208
+
public function renderIf($item, View $view) // add the view parameter
209
+
{
210
+
// your content
211
+
}
212
+
}
213
+
```
214
+
**Publish config file (Optional)**
215
+
216
+
Some new variants have been added to the config file, if you have published the config file before, you could publish it again so you can customize the new variants, this doesn't affect anything at all since the new variants will be taken from the default config file.
217
+
218
+
**Remove `repository` method from your views (Optional)**
219
+
220
+
If your `repository()` methods are returning a query object without any other query applied like `User::query()`, you can define a `protected $model = User::class;` instead, this is the default behavior now, the `repository()` method is still working so you don't need to change anything if you don't want to.
@@ -30,17 +32,33 @@ With this artisan command a `ExampleGridView.php` file will be created inside `a
30
32
31
33
## Defining initial data
32
34
33
-
Return an `Eloquent` query with the initial data to be displayed on the grid view, it is important to return the query, not the data collection.
35
+
The GridView class needs a model class to get the initial data to be displayed on the table, you can define it in the `$model` property.
34
36
35
37
```php
36
38
use App\User;
37
39
40
+
protected $model = User::class;
41
+
```
42
+
43
+
If you need an specific query as initial data you can define a `repository` method returning an `Eloquent` query with the initial data to be displayed on the grid view, it is important to return the query, not the data collection.
44
+
45
+
```php
46
+
use App\User;
47
+
use Illuminate\Database\Eloquent\Builder;
48
+
49
+
/**
50
+
* Sets a initial query with the data to fill the table
51
+
*
52
+
* @return Builder Eloquent query
53
+
*/
38
54
public function repository(): Builder
39
55
{
40
56
return User::query();
41
57
}
42
58
```
43
59
60
+
If you define this method, the `$model` property is not needed anymore.
61
+
44
62
## Defining card data
45
63
46
64
You have to define a public function returning an array with the data that will be displayed on each card, this array has to include `photo`, `title`, `subtitle` and the `description`.
@@ -61,10 +79,45 @@ These are the fields by default but you can add more if you want to customize yo
61
79
62
80
## Customizing card data
63
81
64
-
The grid view has a card component by default with some data but you can either create your own card and use as much data as you need in the `card`mthod and just use your own card implementation, you just need to specify a blade file.
82
+
The grid view has a card component by default with some data, however, you can create your own card component and use as much data as you need in the `card`method, you just need to specify a blade file with your Grid View and return the data that you need in the `card` method.
65
83
66
84
```php
67
85
public $cardComponent = 'components.my-card';
86
+
87
+
public function card($model) {
88
+
return [
89
+
'name' => $model->name,
90
+
'email' => $model->email,
91
+
'model' => $model
92
+
];
93
+
}
94
+
```
95
+
96
+
All the data returned in the `card` method will be received as a prop in your blade component alog with these other default props that you can use based on your needs.
97
+
98
+
Name|Description|Type|Value
99
+
--|--|--|--|
100
+
model|Model instance for this card|||
101
+
actions|Actions defined in this view class|Array
102
+
hasDefaultAction|Checks if the Grid View has defined a `onCardClick` method|Boolean|true,false
103
+
selected|Defines if the item was selected when the grid view has bulk actions|Boolean|true,false
104
+
105
+
With all this data you can build your own card component as you need, remember to include an `actions` component.
You can define a default action that will be fired clicking on the card image or the card title, this action gets the model instance that fired it.
116
+
117
+
```php
118
+
public function onCardClick(User $model)
119
+
{
120
+
}
68
121
```
69
122
70
123
## Max columns
@@ -84,6 +137,19 @@ public $withBackground = true
84
137
85
138
This will render the item with a white background.
86
139
140
+
## Sorting data
141
+
You can add an option to sort the items on the grid view by an specific field defining a `sortableBy` method with an array of the fields to sort by, as the grid view desn't have headers, a `Sort by` button will be displayed with a drop down with all the fields defined in this method.
142
+
143
+
```php
144
+
public function sortableBy()
145
+
{
146
+
return [
147
+
'Name' => 'name',
148
+
'Email' => 'email'
149
+
];
150
+
}
151
+
```
152
+
87
153
## More features
88
154
This grid view is based on a table view, so you could use some of the table view features as:
If you dont need to include `Tailwindcss`or `Livewire` assets you can just set the `laravel-views` assets in the list.
75
+
If you dont need to include `Tailwindcss`, `Livewire`or `Alpine` assets you can just set the `laravel-views` assets in the list.
75
76
76
77
```php
77
78
@laravelViewsStyles(laravel-views)
79
+
@laravelViewsScripts(laravel-views)
78
80
```
79
81
82
+
This is recomended for a production environment where you surely have a compile assets pipeline, like Laravel Mix, or you want to include the assets from a CDN on your own.
83
+
80
84
## Purge Tailwindcss styles
81
85
If you're using your own Tailwindcss setup you must consider `laravel-views` in your `purge` configuration, for that just add this path to the `purge` array on the `tailwind.config.js`file.
82
86
83
87
```js
84
-
purge: {
85
-
content: [
86
-
//...Rest of your paths
87
-
"./vendor/laravel-views/**/*.php",
88
-
],
89
-
},
88
+
purge: [
89
+
//...Rest of your paths
90
+
"./vendor/laravel-views/**/*.php",
91
+
],
90
92
```
91
93
92
94
# First table view
@@ -147,63 +149,11 @@ In the example above the view is using the User model created by default in ever
147
149
This is the basic usage of the table view, but you can customize it with more features.
148
150
149
151
[Read the full table view documentation ](doc/table-view.md)
150
-
151
-
# Rendering a view from a controller
152
-
153
-
You can render a view manually in a controller creating a `LaravelViews` instance and executing the `render` method on a `blade` file.
These views are build with [Tailwind CSS](https://tailwindcss.com/) and you can either change the colors of the components following tailwindcss utilities or fully customize all the html of the components
204
154
205
155
## Component variants using tailwindcss
206
-
If you are using [Tailwind CSS](https://tailwindcss.com/) or if you don't have issues using Tailwindcss and your own css styles, you can customize some utilities to change the color for each variant of the components publishing a config file
156
+
You can customize some of the components styles (like the color) for each one of the variants with a config file.
0 commit comments