Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vojislavd/tall-components
Library of useful UI components for TALL stack
https://github.com/vojislavd/tall-components
alpinejs livewire tailwindcss tall tall-components
Last synced: about 2 months ago
JSON representation
Library of useful UI components for TALL stack
- Host: GitHub
- URL: https://github.com/vojislavd/tall-components
- Owner: VojislavD
- License: mit
- Created: 2024-01-27T09:20:29.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2024-03-18T20:19:16.000Z (9 months ago)
- Last Synced: 2024-11-07T05:50:07.222Z (about 2 months ago)
- Topics: alpinejs, livewire, tailwindcss, tall, tall-components
- Language: PHP
- Homepage:
- Size: 1.32 MB
- Stars: 2
- Watchers: 1
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# TALL components
Library of useful UI components created for TALL (Tailwind CSS, Alpine.js, Laravel, Livewire) stack.
Include:
- [x] [Modal](#modal)
- [x] [Confirmation modal](#confirmation-modal)
- [x] [Notification](#notification)
- [x] [Table (search, filters, sort columns)](#table)
- [x] [Loading spinner](#loading-spinner)
- [x] [Drag & drop file upload (Filepond)](#drag--drop-file-upload-filepond)
- [x] [Markdown editor (Quill)](#markdown-editor-quill)
- [x] [Datetime picker (Flatpickr)](#datetime-picker-flatpickr)
## Requirements
This package requires having installed and working Laravel, Tailwind CSS, Alpine.js and Livewire.
The package is created and tested for these frameworks:
- Laravel v10
- Tailwind CSS v3
- Alpine.js v3
- Livewire v3
There can be some differences for other versions.
## Installation
You can install the package via composer:
```bash
composer require vojislavd/tall-components
```
You need to include `tc.js` in your `resources/js/app.js` file:
```js
import './../../vendor/vojislavd/tall-components/resources/js/tc.js'
```
Next, you should compile assets:
```bash
npm install && npm run build
```
Components will use `primary`, `primary-dark`, `secondary` and `secondary-dark` colors. You should configure these colors in your `tailwind.config.js` file.
If you want to change colors or customize anything else, you can publish all components views with:
```bash
php artisan vendor:publish --tag="tall-components-views"
```
To change colors, just find `primary`, `primary-dark`, `secondary` or `secondary-dark` in the component and replace them with color you want to use.
## Usage
### Modal
To use modal, you need have boolean variable inside your Livewire component. Modal will be opened or closed based on the value of that variable.
```php
` and set `model` property to match boolean variable you added in the PHP file of your Livewire component.
Inside `` tags, you can add any content you want to be present in modal.
```blade
This is some title
This is some content
```
The modal can be opened from the blade file, like this:
```blade
Open my modal
```
Or it can be opened from a PHP file, like this:
```php
openModal = true;
}
}
```
The same goes for closing the modal, only the value of `openModal` will be set to `false`.
For example, if you want to have a button to close the modal inside the modal itself, you can do it like this:
```blade
... Some content of modal
Cancel
```
It's possible to configure the width of the modal by passing a Tailwind CSS class to `width` property of the component. For example:
```blade
... Some content of modal
```
You can add action buttons to the bottom of the modal like this:
```blade
... Some content of modal
Cancel
Submit
```
### Confirmation modal
To use the confirmation modal, you need to add the `x-tc-confirmation-modal` component and the `WithTcConfirmation` trait to the Livewire component where you want to use it.
```php
```
Then, to require confirmation for some action, you should add `x-tc-confirm` to the button from which you want to trigger the confirmation modal and pass `title`, `message`, and `action`.
`action` should be a Livewire method you want to call after the user clicks the "Confirm" button in the modal.
```blade
You can display notifications on the same page without reloading, or you can redirect to some other page and display notifications on that page.
To use notifications, the recommended way is to add them to your layout file, so notifications will be available on all pages.
You should add this Livewire component at the end of the file, before `@livewireScripts`.
```blade
@livewire('tc-notification)
// or
```
If you want to display notifications from a Livewire component without reloading the page, all you need to do is dispatch `notification` event with the message you want to display, like this:
```php
dispatch('notification', 'Message to display in notification');
}
}
```
If you want to redirect to some other page and display a notification there, you can do it like this:
```php
with('notification', 'Message to display in notification');
}
}
```
Notification will disappear by default after 5 seconds (5000 ms). To change that, you need to pass the duration parameter to the component. Duration is represented in milliseconds.
For example, to change the notification to disappear after 3 seconds, you can do it like this:
```blade
@livewire('tc-notification, ['duration' => 3000])
// or
```
### Table
You can use a table in the blade file of your Livewire component like this:
```blade
Name
Email
Status
Created at
@forelse($this->users as $user)
{{ $user->name }}
{{ $user->email }}
{{ $user->status }}
{{ $user->created_at->format('d.m.Y H:i') }}
@empty
There is no results
@endforelse
{{ $this->users->links() }}
```
And in Livewire component, you need to add the `WithTcTable` trait. When you are getting rows for the table (such as `$this->users` in this example), you can use filters like this:
```php
when($this->tcSearch, function ($query) {
$query->where('name', 'LIKE', '%' . $this->tcSearch . '%');
})
->when($this->onlyActive, function ($query) {
$query->where('is_active', true);
})
->when($this->tcSortable === 'name', function ($query) {
$query->orderBy('name', $this->tcSortDirection);
})
->when($this->tcSortable === 'email', function ($query) {
$query->orderBy('email', $this->tcSortDirection);
})
->paginate($this->tcPerPage);
}
}
```
#### Clickable rows
It is possible to allow rows to be clickable by adding the `href` attribute to the `x-tc-tr` component and passing the value where you want to be redirected.
For example, to redirect to the user profile page with the route name `users.show`, you can do it like this:
```blade
```
#### Search filter
Search filter is optional; if you don't need it, you can leave out ``. In that case, there will be no input for searching the table.
The value of the search input is stored in the `tcSearch` variable. So, to filter the table based on the value from that field, you need to use `$this->tcSearch`.
#### Custom filters
You can add any custom filter you want (In the case above, it's the `Only active` filter). You can pass any toggle, checkbox, or select input inside the `` slot.
#### Per page filter
Per page filter is optional; if you don't need it, you can leave out ``.
The value of per page is stored in the `tcPerPage` variable, and it is `15` by default. To use it, you need to pass `$this->tcPerPage` to your `paginate` method, like this:
```php
...
->paginate($this->tcPerPage);
```
You can customize the number of rows users can choose by passing values as the `options` attribute to the `x-tc-per-page` component. For example, if you want to allow users to choose between `15`, `30`, and `50`, you can do it like this:
```blade
```
#### Sort by columns
You can allow sorting by any column in the table by adding `sortable` to the `` component and by passing the key for sorting, which you will use in Livewire components.
For example, if you want to allow sorting by user name, you can do it like this:
```blade
Name
```
And then you can sort results based on name like this:
```php
...
->when($this->tcSortable === 'name', function ($query) {
$query->orderBy('name', $this->tcSortDirection);
})
```
Name of the sortable column is stored in `tcSortable`, and direction is stored in the `tcSortDirection` variable. Direction will be `asc` by default and will switch between `asc` and `desc` on every click.
#### Pagination
Pagination is optional; if you don't need it, you can leave out ``.
### Loading spinner
Add `` to your blade and add a `target` attribute that should match the Livewire action you want to use the spinner for.
```blade
```
```php
```
Or if you want to make some other changes, you can publish the view file and do it there.
### Drag & drop file upload (Filepond)
To use a field for file uploading, you need to add `` to your blade and set `wire:model`.
```blade
```
When file is uploaded it will be standard Livewire temporary uploaded file (`Livewire\Features\SupportFileUploads\TemporaryUploadedFile`) and you can save it as any other file upload.
If you want to call a Livewire action immediately after a file is uploaded, you can add `callOnUpload` to the component and pass the name of the Livewire method you want to be called. For example, to call the `saveFile` method after a file is uploaded:
```blade
```
You can reset Filepond field from Livewire by dispatching event that will match `resetKey` of component. For example:
```blade
```
```php
dispatch('resetFileField');
}
}
```
The component allows different configurations, with the following available properties:
| PROPERTY | DEFAULT VALUE | DESCRIPTION |
|-------------------------|---------------|-------------------------------------------------------------------------------------|
| allowDrop | `true` | Enable or disable drag n' drop |
| allowBrowse | `true` | Enable or disable file browser |
| allowPaste | `true` | Enable or disable pasting of files. Pasting files is not supported on all browsers |
| allowMultiple | `false` | Enable or disable adding multiple files |
| allowFileSizeValidation | `true` | Enable or disable file size validation |
| minFileSize | `null` | The minimum size of a file, for instance `5MB` or `750KB` |
| maxFileSize | `null` | The maximum size of a file, for instance `5MB` or `750KB` |
| allowFileTypeValidation | `true` | Enable or disable file type validation |
| acceptedFileTypes | `[]` | Array of accepted file types. Can be mime types or wild cards. For instance ['image/*'] will accept all images. ['image/png', 'image/jpeg'] will only accepts PNGs and JPEGs. |
| allowImagePreview | `true` | Enable or disable preview mode |
| imagePreviewMinHeight | `44` | Minimum image preview height |
| imagePreviewMaxHeight | `256` | Maximum image preview height |
If you want to make other changes, you can publish views and edit the `filepond.blade.php` file.
### Markdown editor (Quill)
To use a Quill text editor, you need to add `` to your blade and set `wire:model` (it's not possible to use `live` or `blur`).
```blade
```
You can add placeholder text by passing the `placeholder` attribute to the component.
```blade
```
It's possible to make the editor read-only; just pass the `readOnly` attribute and set it to be true.
```blade
```
Editor will include all editing options in the toolbar by default. You can configure it by passing the `toolbar` attribute to the component with the editing options you want to use. For example, if you want to have only the `bold`, `italic`, and `underline` options:
```blade
```
Editor's default toolbar:
```
['bold', 'italic', 'underline', 'strike'],
['blockquote', 'code-block'],
['link', 'formula'],
[{ 'header': 1 }, { 'header': 2 }],
[{ 'list': 'ordered'}, { 'list': 'bullet' }, { 'list': 'check' }],
[{ 'script': 'sub'}, { 'script': 'super' }],
[{ 'indent': '-1'}, { 'indent': '+1' }],
[{ 'direction': 'rtl' }],
[{ 'size': ['small', false, 'large', 'huge'] }],
[{ 'header': [1, 2, 3, 4, 5, 6, false] }],
[{ 'color': [] }, { 'background': [] }],
[{ 'font': [] }],
[{ 'align': [] }],
['clean']
```
If you want to change the theme of the editor or make any other modifications, you can publish views and edit the `quill-editor.blade.php` file.
### Datetime picker (Flatpickr)
To use the datetime picker, you need to add `` to your blade and set `wire:model`.
```blade
```
To add a placeholder, just pass the `placeholder` attribute to components:
```blade
```
The component allows for different configurations; you can pass attributes to the component to change its configuration.
Available properties:
| PROPERTY | TYPE | DEFAULT VALUE | EXAMPLE VALUE |
|--------------|-------------|---------------|----------------------------------|
| dateFormat | String | `Y-m-d` | `d.m.Y` |
| minDate | String/Date | `null` | `2024-03-01` |
| maxDate | String/Date | `null` | `2024-03-10` |
| defaultDate | String | `null` | `2024-03-02` |
| enableTime | Boolean | `false` | `true` |
| time_24hr | Boolean | `false` | `true` |
| minTime | String | `null` | `09:00` |
| maxTime | String | `null` | `11:00` |
| mode | String | `single` | `single`, `multiple`, or `range` |
| noCalendar | Boolean | `false` | `true` |
If you want to make additional changes, you can publish views and edit the `datetime-picker.blade.php` file.
## Testing
Run tests with:
```bash
composer test
```
## Credits
- [Vojislav Dragicevic](https://vojislavd.com/)
## License
The MIT License (MIT). Please see [License File](LICENSE.md) for more information.