|
| 1 | +# Detail view |
| 2 | + |
| 3 | +This view creates a dynamic detail view to render a model attributes list with all the data you need, you can also customize the default component to create complex detail views and execute actions over the model is being used. |
| 4 | + |
| 5 | +- [Home](../README.md) |
| 6 | +- [Detail view](#detail-view) |
| 7 | +- [Creating a new detail view](#creating-a-new-detail-view) |
| 8 | +- [Defining initial model](#defining-initial-model) |
| 9 | +- [Defining the heading](#defining-the-heading) |
| 10 | +- [Defining the detail data](#defining-the-detail-data) |
| 11 | +- [Customizing the default component](#customizing-the-default-component) |
| 12 | +- [Using more components](#using-more-components) |
| 13 | +- [Actions](#actions) |
| 14 | + |
| 15 | +## Detail view example |
| 16 | + |
| 17 | + |
| 18 | + |
| 19 | +## Creating a new detail view |
| 20 | + |
| 21 | +```bash |
| 22 | +php artisan make:view detail ExampleDetailView |
| 23 | +``` |
| 24 | + |
| 25 | +With this artisan command an `ExampleDetailView.php` file will be created inside the `app/Http/Livewire` directory, with this class you can customize the behavior of the detail view. |
| 26 | + |
| 27 | +```php |
| 28 | +<?php |
| 29 | + |
| 30 | +namespace App\Http\Livewire; |
| 31 | + |
| 32 | +use LaravelViews\Views\DetailView; |
| 33 | + |
| 34 | +class ExampleDetailView extends DetailView |
| 35 | +{ |
| 36 | + public $title = "Title"; |
| 37 | + public $subtitle = "Subtitle or description"; |
| 38 | + |
| 39 | + /** |
| 40 | + * @param $model Model instance |
| 41 | + * @return Array Array with all the detail data or the components |
| 42 | + */ |
| 43 | + public function detail($model) |
| 44 | + { |
| 45 | + return [ |
| 46 | + 'Name' => $model->name, |
| 47 | + 'Email' => $model->email, |
| 48 | + ]; |
| 49 | + } |
| 50 | +} |
| 51 | +``` |
| 52 | + |
| 53 | +## Defining initial model |
| 54 | + |
| 55 | +The detail view uses a model instance as a data source, you have to set the model when you are rendering the component. |
| 56 | + |
| 57 | +```html |
| 58 | +<livewire:example-detail-view :model="$myModelInstance" /> |
| 59 | +``` |
| 60 | + |
| 61 | +You can set an `id` instead of a model instance, which will be created by the detail view. You must set a `$modelClass` property on your detail view to set the model class will be used to create the instance. |
| 62 | + |
| 63 | +```html |
| 64 | +<livewire:example-detail-view :model="1" /> |
| 65 | +``` |
| 66 | + |
| 67 | +```php |
| 68 | +protected $modelClass = \App\User::class; |
| 69 | +``` |
| 70 | + |
| 71 | +## Defining the heading |
| 72 | + |
| 73 | +You can set a title and a subtitle to the detail view changing the value of the `$title` and `subtitle` as you need. |
| 74 | + |
| 75 | +```php |
| 76 | +public $title = "My custom title"; |
| 77 | +public $subtitle = "My custom subtitle"; |
| 78 | +``` |
| 79 | + |
| 80 | +If you need access to the model instance to set the title and subtitle, you can define a `heading` method returning an array with both values. |
| 81 | + |
| 82 | +```php |
| 83 | +public function heading($model) |
| 84 | +{ |
| 85 | + return [ |
| 86 | + "This is the detail view of {$model->name}", |
| 87 | + "This is the subtitle of {$model->name}", |
| 88 | + ]; |
| 89 | +} |
| 90 | +``` |
| 91 | + |
| 92 | +## Defining the detail data |
| 93 | + |
| 94 | +The detail view will render an attributes list and will pass dynamically all the data defined in the `detail` method. |
| 95 | +You have to define a public function returning an array with the data that will be sent to the attributes list. |
| 96 | + |
| 97 | +```php |
| 98 | +public function detail($model) |
| 99 | +{ |
| 100 | + return [ |
| 101 | + 'Name' => $model->name, |
| 102 | + 'Email' => $model->email, |
| 103 | + // ...rest of the attributes |
| 104 | + ]; |
| 105 | +} |
| 106 | +``` |
| 107 | + |
| 108 | +The default component will render an attributes list using an associative array to render the labels and the values. |
| 109 | + |
| 110 | +Using this data array you can create simple detail views without any HTML code. |
| 111 | + |
| 112 | + |
| 113 | +## Customizing the default component |
| 114 | + |
| 115 | +If you dont want to use the default attributes list, you can create your own component and defining it in the `$detailComponent` property on your detail view class, all the data returned in the `detail` method will be passed as an attribute to your component. |
| 116 | + |
| 117 | +```php |
| 118 | +protected $detailComponent = 'components.my-attributes-list-component'; |
| 119 | + |
| 120 | +public function detail($model) |
| 121 | +{ |
| 122 | + return [ |
| 123 | + 'name' => $model->name, |
| 124 | + 'email' => $model->email, |
| 125 | + // ...rest of the attributes |
| 126 | + ]; |
| 127 | +} |
| 128 | +``` |
| 129 | + |
| 130 | +```html |
| 131 | +<!-- resources/views/components/my-attributes-list-component --> |
| 132 | +@props['name', 'email'] |
| 133 | +<ul> |
| 134 | + <li>Name: {{ $name }}<li/> |
| 135 | + <li>Eamil: {{ $email }}<li/> |
| 136 | +</ul> |
| 137 | +``` |
| 138 | + |
| 139 | +## Using more components |
| 140 | +Some detail views can be complexer than a single attributes list, this detail view can render any other type of custom component as it is needed using the `UI` facade instead of a single data array. |
| 141 | + |
| 142 | +```php |
| 143 | +UI::component('components.my-custom-component', ['attribute' => 'value' ]) |
| 144 | +``` |
| 145 | + |
| 146 | +The `component` method of the `UI` class renders a blade component, the first argument is the component's path, and the second argument is an array with all the attributes that will be passed to the component. |
| 147 | + |
| 148 | +```php |
| 149 | +use LaravelViews\Facades\UI; |
| 150 | + |
| 151 | +public function detail($model) |
| 152 | +{ |
| 153 | + return UI::component('components.my-custom-component', ['attribute' => 'value' ]); |
| 154 | +} |
| 155 | +``` |
| 156 | + |
| 157 | +You can set an array with more than one component, the detail view will iterate over it and will render all the components. |
| 158 | + |
| 159 | +```php |
| 160 | +use LaravelViews\Facades\UI; |
| 161 | + |
| 162 | +public function detail($model) |
| 163 | +{ |
| 164 | + return [ |
| 165 | + UI::component('components.my-custom-component', ['attribute' => 'value' ]), |
| 166 | + UI::component('components.my-second-component', ['model' => $model]), |
| 167 | + UI::attributes([ |
| 168 | + 'Name' => $model->name, |
| 169 | + 'Email' => $model->email |
| 170 | + ]) |
| 171 | + ]; |
| 172 | +} |
| 173 | +``` |
| 174 | + |
| 175 | +The `attributes` method of the `UI` class is a pre-built component in this package, is the one used by default in de detail view. |
| 176 | + |
| 177 | +Using customized components you can build detail views as complex as you need. |
| 178 | + |
| 179 | + |
| 180 | +## Actions |
| 181 | +The detail view can execute actions over the model is being used, the actions are defined in the `actions` method on the detail view and they have the same behavior as in the other views. |
| 182 | + |
| 183 | +```php |
| 184 | +public function actions() |
| 185 | +{ |
| 186 | + return [ |
| 187 | + new ActivateUserAction, |
| 188 | + new RedirectAction('user', 'See user', 'eye'), |
| 189 | + ]; |
| 190 | +} |
| 191 | +``` |
| 192 | + |
| 193 | +See the [full actions documentation](./table-view#actions) |
0 commit comments