Files
FilePond
{note} You're browsing the documentation for an old version of laravel-form-components. Consider upgrading your project to v8. Check your version with the following command:
composer show rawilk/laravel-form-components
- Introduction
- Installation
- Basic Usage
- Livewire Integration
- Options
- Callbacks
- Plugins
- Manually Deleting Files
- Clear Event Listener
Introduction
The file-pond
component provides an easy way to utilize advanced file uploads via FilePond.
Before using this component, we recommend familiarizing yourself with the FilePond library.
Installation
While the file-pond
component works out-of-the-box when you've set the directive,
we recommend that you install and compile the JavaScript libraries before you deploy to production:
As per the FilePond docs, you can install FilePond via npm:
npm i filepond --save
You can then import it in your project using imports:
import * as FilePond from 'filepond';
There are also some styles required for FilePond. If you're using Sass, you can import it before you import the styles for this package:
@import '~filepond/dist/filepond.min.css';
Basic Usage
The most basic usage of the file-pond
component involves just adding a self-closing tag:
<x-file-pond />
This will output the following HTML (omitting JS):
<div wire:ignore
x-data
x-cloak
x-init="..."
>
<input x-ref="input"
type="file"
style="display:none;"
/>
</div>
Livewire Integration
The file-pond
component integrates smoothly with livewire out-of-the-box and just requires you to
provide a wire:model
to the component. This will help it set up the necessary server
configuration
options on the library and will handle uploading and reverting automatically for you via livewire.
<x-file-pond wire:model="avatar" />
Options
You can provide options to the FilePond library via an array through the options
attribute. This requires you
to pass in a PHP array with scalar values only. Below is an example where we set a class of "foo" on the
root element generated by FilePond:
<x-file-pond wire:model="avatar" :options="['className' => 'foo']" />
For a full reference of all options, please consult the FilePond documentation.
Multiple
You can accept multiple files by passing in multiple
as a boolean value. This attribute has been added as a way
to conveniently set the allowMultiple
option for FilePond.
Max Files
You can limit the number of files accepted when allowMultiple
is set to true
by providing max-files
with an
integer value.
Disabled
You can easily disable the FilePond input by passing disabled
in as a boolean value.
Allow Drop
The allow-drop
boolean attribute has been added as a way to conveniently set the allowDrop
option. Setting it to false
will prevent users from being able to drop files onto the input.
Callbacks
Since the options
attribute only accepts scalar values, the component offers an optionsSlot
slot that will allow you to
specify an option callbacks, such as server
that you need to:
<x-file-pond wire:model="avatar">
<x-slot name="optionsSlot">
server: {
process: () => { ... }
}
</x-slot>
</x-file-pond>
Plugins
The file-pond
component doesn't make use of any FilePond plugins itself, but you can easily install and implement your own plugins.
First, install the necessary JavaScript and CSS required by the plugin. A list of plugins can be found here.
With the plugin's assets installed, you can make use of the plugins
slot to initialize the plugin. The following example shows setting up the image
preview FilePond Plugin.
<x-file-pond wire:model="avatar">
<x-slot name="plugins">
FilePond.registerPlugin(FilePondPluginImagePreview);
</x-slot>
</x-file-pond>
If you're into using CDNs, you can add these lines to your layout file for the above example:
<link href="https://unpkg.com/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.css" rel="stylesheet">
<script src="https://unpkg.com/filepond-plugin-image-preview/dist/filepond-plugin-image-preview.js"></script>
Manually Deleting Files
If you decide to do something like list out the files and delete them yourself manually instead of the revert button provided by FilePond, you will
find that the files still appear to be in FilePond, even though Livewire has actually cleared out your wire:model
value. To help with this,
the file-pond
component adds a watcher on your wire:model
by using @entangle
. Now, when you remove the files manually, the component
will pick up on those changes and remove the removed files from the FilePond instance.
You can opt out of this behavior by setting the boolean attribute watch-value
to false
on the component.
Clear Event Listener
You may encounter some edge cases where you may need to clear the files out of the FilePond instance yourself. When using livewire, this can easily be accomplished by adding the following inside your component somewhere:
$this->dispatchBrowserEvent('file-pond-clear', ['id' => $this->id]);
Each Livewire component has its own unique id assigned to it, so by passing $this->id
into the
event you're emitting, the component will be able to match the ids and clear the files for the correct
component.