diff --git a/resources/js/Pages/responses.jsx b/resources/js/Pages/responses.jsx index d765afb2..33d52f25 100644 --- a/resources/js/Pages/responses.jsx +++ b/resources/js/Pages/responses.jsx @@ -5,6 +5,9 @@ export const meta = { title: 'Responses', links: [ { url: '#creating-responses', name: 'Creating responses' }, + { url: '#properties', name: 'Properties' }, + { url: '#provides-inertia-property', name: 'ProvidesInertiaProperty interface' }, + { url: '#provides-inertia-properties', name: 'ProvidesInertiaProperties interface' }, { url: '#root-template-data', name: 'Root template data' }, { url: '#maximum-response-size', name: 'Maximum response size' }, ], @@ -18,10 +21,10 @@ export default function () {

Creating an Inertia response is simple. To get started, invoke the Inertia::render() method within your controller or route, providing both the name of the JavaScript page component that you - wish to render, as well as any props (data) for the page. + wish to render, as well as any properties (data) for the page.

- In the example below, we will pass a single prop (event) which contains four attributes ( + In the example below, we will pass a single property (event) which contains four attributes ( id, title, start_date and description) to the{' '} Event/Show page component.

@@ -66,6 +69,227 @@ export default function () { To ensure that pages load quickly, only return the minimum data required for the page. Also, be aware that all data returned from the controllers will be visible client-side, so be sure to omit sensitive information. +

Properties

+

+ To pass data from the server to your page components, you can use properties. You can pass various types of values as + props, including primitive types, arrays, objects, and several Laravel-specific types that are automatically resolved: +

+ 'Dashboard', + 'count' => 42, + 'active' => true, + + // Arrays and objects + 'settings' => ['theme' => 'dark', 'notifications' => true], + + // Arrayable objects (Collections, Models, etc.) + 'user' => auth()->user(), // Eloquent model + 'users' => User::all(), // Eloquent collection + + // API Resources + 'profile' => new UserResource(auth()->user()), + + // Responsable objects + 'data' => new JsonResponse(['key' => 'value']), + + // Closures + 'timestamp' => fn() => now()->timestamp, + ]); + `, + }, + ]} + /> +

+ Arrayable objects like Eloquent models and collections are automatically converted using their toArray() method. + Responsable objects like API resources and JSON responses are resolved through their toResponse() method. +

+

ProvidesInertiaProperty interface

+

+ When passing props to your components, you may want to create custom classes that can transform themselves into the + appropriate data format. While Laravel's Arrayable interface simply converts objects to arrays, Inertia + offers the more powerful ProvidesInertiaProperty interface for context-aware transformations. +

+

+ This interface requires a toInertiaProperty method that receives a PropertyContext object + containing the property key ($context->key), all props for the page ($context->props), and the + request instance ($context->request). +

+ user->avatar + ? Storage::url($this->user->avatar) + : "https://ui-avatars.com/api/?name={$this->user->name}&size={$this->size}"; + } + } + `, + }, + ]} + /> +

+ You can use this class directly as a prop value: +

+ $user, + 'avatar' => new UserAvatar($user, 128), + ]); + `, + }, + ]} + /> +

+ The PropertyContext gives you access to the property key, which enables powerful patterns like merging + with shared data: +

+ key, []); + + // Merge with the new items + return array_merge($shared, $this->items); + } + } + + // Usage + Inertia::share('notifications', ['Welcome back!']); + + return Inertia::render('Dashboard', [ + 'notifications' => new MergeWithShared(['New message received']), + // Result: ['Welcome back!', 'New message received'] + ]); + `, + }, + ]} + /> +

ProvidesInertiaProperties interface

+

+ In some situations you may want to group related props together for reusability across different pages. You can + accomplish this by implementing the ProvidesInertiaProperties interface. +

+

+ This interface requires a toInertiaProperties method that returns an array of key-value pairs. The + method receives a RenderContext object containing the component name ($context->component) + and request instance ($context->request). +

+ $this->user->can('edit'), + 'canDelete' => $this->user->can('delete'), + 'canPublish' => $this->user->can('publish'), + 'isAdmin' => $this->user->hasRole('admin'), + ]; + } + } + `, + }, + ]} + /> +

+ You can use these prop classes directly in the render() and with() methods: +

+ with($permissions); + } + `, + }, + ]} + /> +

+ You can also combine multiple prop classes with other props in an array: +

+ auth()->user(), + $permissions, + ]); + + // or using method chaining... + + return Inertia::render('UserProfile') + ->with('user', auth()->user()) + ->with($permissions); + } + `, + }, + ]} + />

Root template data

There are situations where you may want to access your prop data in your application's root Blade template. For @@ -84,7 +308,7 @@ export default function () { ]} />

- Sometimes you may even want to provide data to the root template that will not be sent to your JavaScript page / + Sometimes you may even want to provide data to the root template that will not be sent to your JavaScript page component. This can be accomplished by invoking the withViewData method.