diff --git a/event-bus.md b/event-bus.md new file mode 100644 index 0000000..7717714 --- /dev/null +++ b/event-bus.md @@ -0,0 +1,67 @@ +# Event Bus + +Splade has a built-in **Event Bus** that allows for communication between components. Events can be emitted by one component, and listened for by another. + +## Emit from Vue component + +To emit an event, you may call the `emit` method, for example, in a [custom Vue component](/custom-vue-components.md), on the global `$splade` instance: + +```vue + +``` + +If you're using the `setup` attribute on a ` +``` + +Additionally, you may pass data along with the event: + +```js +Splade.emit('checkout', { id: 1 }); +``` + +## Emit on event + +It's also possible to call the `emit` method from another event. For example, the [Form Component](/x-form.md) emits `error` and `success` events that you can hook into: + +```blade + +``` + +## Listen for events + +You may register a listener by using the `on` method: + +```js +this.$splade.on('checkout-failed', function() { + // do something +}); +``` + +When the callback is rather simple, you may use a [Script Component](/x-script.md) to avoid writing a custom Vue component: + +```blade + + $splade.on('checkout-failed', function() { + // do something + }); + +``` \ No newline at end of file diff --git a/form-file.md b/form-file.md index 4773f50..e32c44d 100644 --- a/form-file.md +++ b/form-file.md @@ -22,6 +22,18 @@ The component supports selecting multiple files as well by adding the `multiple` ``` +## Image preview + +You might want to show a preview of the selected image. You may use the `form.$fileAsUrl` method to generate a *base64-encoded* representation of the image, and use it as the source of an `img` element. In addition, with the `show-filename` attribute, you can disable displaying the filename. + +```blade + + + + + + ``` + ## FilePond The [FilePond](https://pqina.nl/filepond/) integration comes with a default stylesheet which you should import into the main JavaScript file. If you've used the automatic installer, it has already done this for you. diff --git a/index.json b/index.json index ff5c4cf..fdd3430 100644 --- a/index.json +++ b/index.json @@ -29,6 +29,8 @@ "Form": "x-form", "Link": "x-link", "Modal": "x-modal", + "Rehydrate": "x-rehydrate", + "Script": "x-script", "State": "x-state", "Teleport": "x-teleport", "Toggle": "x-toggle", @@ -62,6 +64,7 @@ "Advanced": { "State management": "state-management", "Persistent layout": "persistent-layout", + "Event bus": "event-bus", "Customization": "customization", "Translations": "translations", "Exception handling": "exception-handling", diff --git a/x-defer.md b/x-defer.md index 4139346..4c5bc06 100644 --- a/x-defer.md +++ b/x-defer.md @@ -60,6 +60,6 @@ The component can watch a passed value for changes using the `watch-value` attri If you want to watch all form data, you may pass `form.$all` to the `watch-value` attribute. -## Async templates +## Async templates and Rehydration -If you want to load sections of your template asynchronously, check out the [Lazy Loading](/lazy-loading.md) section. \ No newline at end of file +If you want to load sections of your template asynchronously, check out the [Lazy Loading](/lazy-loading.md) section. There's also a [Rehydrate Component](/x-rehydrate.md) to reload a section of your Blade template. \ No newline at end of file diff --git a/x-form.md b/x-form.md index da3c85a..7831b17 100644 --- a/x-form.md +++ b/x-form.md @@ -105,6 +105,26 @@ In addition, you may customize the confirmation dialog: > ``` +### Password Confirmation + +It's even possible to require the user to confirm their password within the confirmation dialog. First, you must register a supporting route using the `spladePasswordConfirmation()` method on the `Route` facade. As of version 1.2.2, the automatic installer does this for you. If you need to register the route manually, make sure it uses the `web` Middleware, for example, in `web.php`: + +```php +Route::spladePasswordConfirmation(); +``` + +Now you may add the `require-password` attribute: + +```blade + +``` + +Only when the password is correct it submits the form. Splade will add the entered password to the form data as a `password` field. This way, you may recheck the password *server-side* in the form target action. For security reasons, this is disabled for `GET` requests. You can change the field by passing a value to the `require-password` attribute: + +```blade + +``` + ## File uploads You may use the input event to bind the selected file to your form data: diff --git a/x-rehydrate.md b/x-rehydrate.md new file mode 100644 index 0000000..2ec12b3 --- /dev/null +++ b/x-rehydrate.md @@ -0,0 +1,46 @@ +# X-Splade-Rehydrate Component + +The **Rehydrate Component** can reload a section of your Blade template. You may combine this component with the [Event Bus](/event-bus.md) to trigger the reload on certain events. + +To get started, wrap the section you want to be *reloadable* in the component. For example, imagine a list of team members: + +```blade + +``` + +You may wrap the list and pass the name of the event to the `on` attribute: + +```blade + +
    + @foreach($team->members as $member) +
  • {{ $member->name }}
    • + @endforeach +
+ +``` + +If there's a form that stays on this page after a successful request, you may emit an event that reloads the list: + +```blade + + + + +``` + +Of course, when the form doesn't have the `stay` attribute and redirects back to the same page, it will reload the complete page, including the list, but you'll lose the state of other components on the page. This pattern can help avoid that. + +## Poll + +You may also use this component to poll for new data. With the `poll` attribute, you can specify the interval in milliseconds. + +```blade + + Today's score: {{ $score }} + +``` \ No newline at end of file diff --git a/x-script.md b/x-script.md new file mode 100644 index 0000000..b7d5508 --- /dev/null +++ b/x-script.md @@ -0,0 +1,20 @@ +# X-Splade-Script Component + +In addition to building [custom Vue components](/custom-vue-components.md), you may use the **Script Component** to add inline scripts to your Blade template. Usually, the Vue render engine would throw an error on script tags, but this component magically injects your script as if it was called in the [`mounted()`](https://vuejs.org/api/options-lifecycle.html#mounted) hook of a Vue component. This way, we can avoid the typical error, and you get access to the global `$splade` object, which you may use to navigate and access the Event Bus. + +Note that this component is quite limited, and it is generally recommended to use custom Vue components. + +```blade + + document.body.classList.add('bg-confetti'); + +``` + +Here's another example of using Splade's navigation capabilities: + +```blade + + setTimeout(() => $splade.visit('/destination'), 5000); + +``` +