Skip to content
This repository was archived by the owner on Mar 18, 2025. It is now read-only.

Commit d8fda4e

Browse files
rawilkrawilk
committed
Add docs for new components
1 parent dadace7 commit d8fda4e

File tree

4 files changed

+240
-1
lines changed

4 files changed

+240
-1
lines changed

‎docs/components/file-upload.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
---
2+
title: File Upload
3+
sort: 15
4+
---
5+
6+
## Introduction
7+
8+
The `file-upload` component provides a custom file input for your forms. It can easily be integrated into your livewire forms
9+
as well just by adding a `wire:model` to the input.
10+
11+
## Installation
12+
13+
Even though the `file-upload` component will work out-of-the-box if you're using the script blade directives in your layout (`@fcScripts`),
14+
we recommend that you install and compile the JavaScript libraries before you deploy to production.
15+
16+
- [Alpine.js](https://github.com/alpinejs/alpine) `^2.7`
17+
18+
## Basic Usage
19+
20+
In its most basic usage, you can use it as a self-closing component and pass it a name:
21+
22+
```html
23+
<x-file-upload name="avatar" />
24+
```
25+
26+
This will output the following HTML:
27+
28+
```html
29+
<div class="file-upload space-x-5">
30+
<div x-data="{ focused: false, isUploading: false, progress: 0 }"
31+
class="space-y-4 w-full"
32+
>
33+
<span class="file-upload__input">
34+
<input x-on:focus="focused = true"
35+
x-on:blur="focused = false"
36+
class="sr-only"
37+
type="file"
38+
name="avatar"
39+
id="avatar"
40+
/>
41+
42+
<label for="avatar"
43+
x-bind:class="{ 'file-upload__label--focused': focused }"
44+
class="file-upload__label"
45+
>
46+
<span role="button"
47+
aria-controls="avatar"
48+
tabindex="0"
49+
>
50+
Select File
51+
</span>
52+
</label>
53+
</span>
54+
</div>
55+
</div>
56+
```
57+
58+
**Note:** Since the component applies a class of `sr-only` (hides the input) to the input itself, the input must have an id assigned to it
59+
for the label to be able to trigger a click on the input. By default, the component assigns the `id` to the `name` attribute if you don't
60+
provide an `id` to it.
61+
62+
## Upload Progress
63+
64+
By default, if you add a `wire:model` to the component, it will hook into livewire's file uploads and display upload progress when
65+
a file is selected. A progress bar indicating upload progress is shown once an upload has been started.
66+
67+
If you would like to not show progress, or to handle the display of the upload progress yourself, you may pass in a false value
68+
for the `display-upload-progress` attribute.
69+
70+
```html
71+
<x-file-upload wire:model="avatar" :display-upload-progress="false" />
72+
```
73+
74+
**Note:** Since the upload progress hooks into livewire events, it will not be shown unless you provide a `wire:model` to it.
75+
76+
## Custom Button Label
77+
78+
By default, the text on the button that is shown says `Select File`. You may optionally specify your own label via an attribute:
79+
80+
```html
81+
<x-file-upload name="avatar" label="Choose New Avatar" />
82+
```
83+
84+
## Default Slot
85+
86+
The `file-upload` component is based on the photo input example from TailwindUI. This displays a photo to the left of the button.
87+
This slot is completely optional, and can be omitted if you don't need to show a file preview.
88+
89+
If you are using livewire and would like to show a photo here, you can do so by following this example:
90+
91+
```html
92+
<x-file-upload name="avatar" wire:model="avatar">
93+
<div>
94+
@if ($avatar)
95+
<span class="block w-20 h-20">
96+
<img class="rounded-full w-full" src="{{ $avatar->temporaryUrl() }}" />
97+
</span>
98+
@endif
99+
</div>
100+
</x-file-upload>
101+
```
102+
103+
## After Slot
104+
105+
You can of course omit the default slot and provide content in the `after` slot to show a file preview on the right side of the button.
106+
Other content could also be shown in this slot as well.
107+
108+
```html
109+
<x-file-upload name="avatar">
110+
<x-slot name="after">
111+
<div>After slot content.</div>
112+
</x-slot>
113+
</x-file-upload>
114+
```
115+
116+
## Multiple Files
117+
118+
You can use the component to upload multiple files by providing the `multiple` attribute to the component. If you're using livewire and `wire:model`, just make
119+
sure you're model is an array to handle the uploads.

‎docs/components/filepond.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: FilePond
3+
sort: 16
4+
---
5+
6+
## Introduction
7+
8+
The `file-pond` component provides an easy way to utilize advanced file uploads via [FilePond](https://pqina.nl/filepond/).
9+
Before using this component, we recommend familiarizing yourself with the FilePond library.
10+
11+
## Installation
12+
13+
While the `file-pond` component works out-of-the-box when you've [set the directive](/docs/laravel-form-components/v1/installation#directives),
14+
we recommend that you install and compile the JavaScript libraries before you deploy to production:
15+
16+
- [Alpine.js](https://github.com/alpinejs/alpine) `^2.7`
17+
- [FilePond](https://pqina.nl/filepond/) `^4.21`
18+
19+
As per the [FilePond docs](https://pqina.nl/filepond/docs/patterns/installation/), you can install FilePond via npm:
20+
21+
```bash
22+
npm i filepond --save
23+
```
24+
25+
You can then import it in your project using imports:
26+
27+
```js
28+
import * as FilePond from 'filepond';
29+
```
30+
31+
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:
32+
33+
```css
34+
@import '~filepond/dist/filepond.min.css';
35+
```
36+
37+
## Basic Usage
38+
39+
The most basic usage of the `file-pond` component involves just adding a self-closing tag:
40+
41+
```html
42+
<x-file-pond />
43+
```
44+
45+
This will output the following HTML (omitting JS):
46+
47+
```html
48+
<div wire:ignore
49+
x-data
50+
x-cloak
51+
x-init="..."
52+
>
53+
<input x-ref="input"
54+
type="file"
55+
style="display:none;"
56+
/>
57+
</div>
58+
```
59+
60+
## Livewire Integration
61+
62+
The `file-pond` component integrates smoothly with livewire out-of-the-box and just requires you to
63+
provide a `wire:model` to the component. This will help it set up the necessary `server` configuration
64+
options on the library and will handle uploading and reverting automatically for you via livewire.
65+
66+
```html
67+
<x-file-pond wire:model="avatar" />
68+
```
69+
70+
## Options
71+
72+
You can provide options to the FilePond library via an array through the `options` attribute. This requires you
73+
to pass in a PHP array with scalar values only. Below is an example where we set a class of "foo" on the
74+
root element generated by FilePond:
75+
76+
```html
77+
<x-file-pond wire:model="avatar" :options="['className' => 'foo']" />
78+
```
79+
80+
For a full reference of all options, please consult [the FilePond documentation](https://pqina.nl/filepond/docs/patterns/api/filepond-instance/#properties).
81+
82+
### Multiple
83+
84+
You can accept multiple files by passing in `multiple` as a boolean value. This attribute has been added as a way
85+
to conveniently set the `allowMultiple` option for FilePond.
86+
87+
### Max Files
88+
89+
You can limit the number of files accepted when `allowMultiple` is set to `true` by providing `max-files` with an
90+
integer value.
91+
92+
### Disabled
93+
94+
You can easily disable the FilePond input by passing `disabled` in as a boolean value.
95+
96+
### Allow Drop
97+
98+
The `allow-drop` boolean attribute has been added as a way to conveniently set the `allowDrop` option. Setting it to `false`
99+
will prevent users from being able to drop files onto the input.
100+
101+
## Callbacks
102+
103+
Since the `options` attribute only accepts scalar values, the component offers an `optionsSlot` slot that will allow you to
104+
specify an option callbacks, such as `server` that you need to:
105+
106+
```html
107+
<x-file-pond wire:model="avatar">
108+
<x-slot name="optionsSlot">
109+
server: {
110+
process: () => { ... }
111+
}
112+
</x-slot>
113+
</x-file-pond>
114+
```

‎resources/views/components/files/file-pond.blade.php‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,10 @@
2525
type="file"
2626
style="display:none;"
2727
@if ($accepts()) accept="{{ $accepts() }}" @endif
28+
29+
@if ($hasErrorsAndShow($name))
30+
aria-invalid="true"
31+
@endif
2832
{{ $attributes->except('wire:model') }}
2933
/>
3034
</div>

‎src/Components/Files/FilePond.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@ public function __construct(
3737
bool $disabled = false,
3838
int $maxFiles = null,
3939
string $type = null,
40-
string $description = null
40+
string $description = null,
41+
bool $showErrors = true
4142
) {
4243
$this->multiple = $multiple;
4344
$this->allowDrop = $allowDrop;
@@ -47,6 +48,7 @@ public function __construct(
4748
$this->type = $type;
4849
$this->options = $options;
4950
$this->description = $description;
51+
$this->showErrors = $showErrors;
5052
}
5153

5254
public function options(): array

0 commit comments

Comments
 (0)