Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/daguilarm/laravel-action-forms
A package to manage forms with Laravel, using only one blade file for all your views (create, edit and show).
https://github.com/daguilarm/laravel-action-forms
alpinejs forms javascript laravel tailwindcss
Last synced: about 1 month ago
JSON representation
A package to manage forms with Laravel, using only one blade file for all your views (create, edit and show).
- Host: GitHub
- URL: https://github.com/daguilarm/laravel-action-forms
- Owner: daguilarm
- License: mit
- Created: 2022-09-02T07:46:42.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2022-09-15T17:45:53.000Z (over 2 years ago)
- Last Synced: 2024-05-20T16:30:00.903Z (7 months ago)
- Topics: alpinejs, forms, javascript, laravel, tailwindcss
- Language: Blade
- Homepage:
- Size: 1.48 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# laravel-action-forms (project in development...)
A package to manage forms with Laravel, using only one blade file for all your views (create, edit and show). You will only need to create a file with your form (only once), and the package will automatically generate the views to `create`, `edit` and `show`.
With this example:
```html
```
Will get this:
## Index
- [Install](#install)
- [Requirements and configuration](#requirements-and-configuration)
- [The show view](#the-show-view)
- [Form](#create-a-form-component)
- [Attribute: data](#data)
- [Attribute: view](#view)
- [Attribute: method](#method)
- [Default attributes for all the components](#default-attributes-for-all-the-components)
- [Attribute: label](#label)
- [Attribute: width](#width)
- [Attributes: dependOn, dependOnType and dependOnValue](#dependon-dependontype-and-dependonvalue)
- [Attribute: conditional](#conditional)
- [Attribute: helper](#helper)
- [Input](#create-an-input-component)
- [Attribute: addons. You can add content before or after the field](#addons)
- [Textarea](#create-a-textarea-component)
- [Attribute: maxlength](#maxlength)
- [Attribute: rows](#rows)
- [Attribute: counter](#counter)
- [Checkbox](#create-a-checkbox-component)
- [Attribute: checked](#checked)
- [Radio button](#create-a-radio-component)
- [Attribute: position](#position)
- [Attribute: options](#options)
- [Select](#select)
- [Attribute: options](#options)
- [Attribute: default](#default)
- [File](#file)
- [Search / Datalist](#search--select-with-search)
- [Attribute: requestFromArray](#requestFromArray)
- [Attribute: requestFrom](#requestFrom)
- [Attribute: requestId](#requestId)
- [Attribute: requestValue](#requestValue)
- [Attribute: minChars](#minchars)
- [Toogle](#toggle)
- [Attribute: color](#color)
- [Button](#button)
- [Attribute: text](#text)
- [Attribute: type](#type)
- [Attribute: color](#color)
- [Attribute: javascript](#javascript)
- [Element group](#groups)
- Attribute: width
- [Attribute: align](#align)
- Attribute: position
- [Roadmap](#roadmap)
## Install
```bash
composer require daguilarm/laravel-action-forms
```
## Requirements and configuration
This package use:
- https://tailwindcss.com/docs/installation
- https://alpinejs.dev/essentials/installation
- https://flatpickr.js.org/getting-started/
If you prefer, you can add this requirements using CDN. We have created a few **Blade Directives** in order to help you. You can add this **Blade Directives** between your ``:
```php
@ActionForms
```
```php
@ActionFormsAlpine
```
```php
@ActionFormsTailwind
```
```php
@ActionFormsFlatpickr
```
At the end of your `` tag, add the stack for the scritps:
```php
@stack('action-forms-scripts')
```
If you are using `PostCss` in your Tailwindcss configuration, you will need to add the following lines in your `tailwind.config.js`:
```js
module.exports = {
content: [
...
'./vendor/daguilarm/laravel-action-forms/resources/views/**/*.php',
'./vendor/daguilarm/laravel-action-forms/config/*.php',
],
```
With this, when `PostCss` will scan all package and it will discover all classes used. You have also a file in `config/action-forms-tailwind-safe.php` where you can add your tailwind safe list, in case you need it. This is useful if you are using conditional clases in your blade templates:
```js
// Tailwind Safe list
return [
'border border-slate-400 border-red-400 border-yellow-400 border-cyan-400 border-green-400',
'text-white',
'w-4 h-4',
'rounded-md rounded-full',
'bg-slate-500 bg-red-500 bg-yellow-500 bg-cyan-500 bg-green-500',
'hover:bg-slate-600 hover:bg-red-600 hover:bg-yellow-600 hover:bg-cyan-600 hover:bg-green-600',
'flex items-center justify-start justify-end justify-center',
'space-x-4 space-y-4',
'w-1/5 w-1/4 w-1/3 w-2/5 w-1/2 w-3/5 w-2/3 w-3/4 w-4/5 w-11/12 w-full',
];
```
> Remember: if you are changing some tailwind class in the config files, you will need to clear views each time you change something in the package theme.
You can also modify the package theme, using the config file:
```js
/*
|--------------------------------------------------------------------------
| Theme
|--------------------------------------------------------------------------
*/
'theme' => [
'label' => [
'text' => 'text-base text-gray-500 font-medium',
],
'input' => [
'bg' => 'bg-white',
'text' => 'text-base text-gray-500', // Text color for input, textarea,...
'border' => 'border-gray-200',
'focus' => 'focus:border-gray-500 focus:ring-gray-500', // Border color on focus for input, textarea,...
'placeholder' => 'placeholder:text-gray-300 placeholder:italic',
'helper' => 'text-sm text-gray-400 italic',
'addons' => [
'text' => 'text-white',
'bg' => 'bg-gray-400',
'border' => 'border border-gray-400',
],
'shadow' => 'shadow',
],
'messages' => [
'errors' => [
'text' => 'text-sm text-red-500 font-semibold',
'border' => 'border-red-500',
]
],
],
```
You can add a prefix to your components, using the config file:
```php
/*
|--------------------------------------------------------------------------
| Components prefix
|--------------------------------------------------------------------------
| By default the component will be like thid:
| You can custom the component like:
*/
'components_prefix' => '',
```
For example:
```php
'components_prefix' => 'laravel',
```
Now the components will looks like:
```html
```
> In the config file, you will find a lot of configuration options.
For this, you will need to publish the configuration file:
```bash
php artisan vendor:publish --provider="Daguilarm\ActionForms\CookieConsentServiceProvider"
```
## Important!
- In order to eliminate problems, always add an `id` attribute to each component.
- Don't use all the dependencies. Each component will inform you of the dependencies it requires.
## The show view
The show view is used to display the content of the form, but without using its elements.
**Show view without boolean fields:**
**Show view with boolean fields:**
## Create a Form component
```html
...
```
An `form` field, has also a list of custom parameters like:
### data
It is the current model result. You have to pass the data for model binding.
### view
It is the current view action: `edit`, `create` or `show`. This is just for render the custom view for each action. **It is a very important attribute.**
### method
The soported methods that can be used in the form are:
- **post**: Is the default value if you keep this attribute empty. Will send a `POST` `_method` to **Laravel**.
- **get**: Will send a `GET` `_method` to **Laravel**.
- **update** and **edit**: Will send a `PATCH` `_method` to **Laravel**. You can use either.
- **delete** and **destroy**: Will send a `DELETE` `_method` to **Laravel**. You can use either.
## Default attributes for all the components
All the components (except `form`) share a series of common methods, apart from those specific to each one of them. Next, we will explain these common methods:
### label
Will render a `` tag like: `My name`.
### width
The `width` parameter allow you to set the container width using **tailwindcss** styles like: `w-1/2`, `w-2/3`,... If you remove the `width` parameter, the default value will be `w-full`. The defult values supported by the package are:
- `w-1/5`: 20%
- `w-1/4`: 25%
- `w-1/3`: 33.33%
- `w-2/5`: 40%
- `w-1/2`: 50%
- `w-3/5`: 60%
- `w-2/3`: 66%
- `w-3/4`: 75%
- `w-4/5`: 80%
- `w-11/12`: 91.6%
- `w-full`: 100%
You can add more in the in the file `config/action-forms-tailwind-safe.php`.
### dependOn, dependOnType and dependOnValue
This will allow us to create dependent fields, for example:
```html
```
In this case, the `surname` field will be hidden until the `name` field has a value. The system will be watching the `name` field until an `onchange` event occurs, and then it will check if the `name` field is still empty, if not, it will display the `surname` field.
The `dependOnType()` attribute admits two possible values: `hidden` or `disabled`.
The `dependOnValue()` attribute will check the parent value with the required value and enable or diable the field base on the result.
**Dependent fields in action:**
**Dependent fields disabled:**
> **The dependent system only works on one level**. That is, a parent element enables or disables their children elements, but it does not trigger a cascade of events towards its own children and these to their children, etc...
### Conditional
Show or hide a component base on a condition:
> If you want to set a default condition, don't forget to send the value as a variable, using the colon character: `:conditional="true"`.
### helper
Will show a helper message after the field.
## name
You can add relationships using dot notation:
Will be equivalen to:
```php
$data->user->profile_avatar;
```
## Create an Input component
> This component requires the **alpinejs** dependency.
The `input` field use all the supported parameters, like: `type`, `name`, `placehoder`, `required`, etc... The basic example of an `input` field will be:
```html
```
An `input` field, has also a list of custom parameters like:
### addons
You can add addons before, after or both. At the moment, it only supports text. In the future it will support icons.
```html
```
## Create a Textarea component
> This component requires the **alpinejs** dependency.
```html
```
An `textarea` field, has also a list of custom parameters like:
### maxlength
It is used to determine the maximum number of characters allowed. By default it will be 220.
### rows
Indicates the default number of rows that the textarea will have. The default value is 4.
### counter
This field is used to indicate if we want to show the characters used and the remaining characters. By default it is disabled.
## Create a Checkbox component
> This component requires the **alpinejs** dependency.
```html
```
### checked
By default, the field will be unchecked.
> If you want to set a default value, don't forget to send the value as a variable, using the colon character `:checked="true"`.
## Create a Radio component
> This component requires the **alpinejs** dependency.
```html
```
### position
You can display the radio button in horizontal or in vertical, using: `position="horizontal"` or `position="vertical"`.
**Radio field with vertical position:**
**Radio field with horizontal position:**
### options
You will need to add and `array` with the `value` and the `text` to be displayed.
> Don't forget to send the value as a variable, using the colon character `:options="[]"`.
## Select
```html
```
**Select and File examples:**
### fromArray
You will need to add and `array` with the `key` and the `value` to be displayed.
### fromUrl
You can define an url to get your data in `JSON` format:
```html
```
### resultKey
You must the define your array key.
### resultValue
You must the define your array value.
### comboboxFrom
```html
```
In this example, the URL for the `JSON` response will be:
```js
let url = 'https://www.domain.com/api/cities?country=' + country.value
```
An will populate the child element with the cities from the selected country (parent element).
### default
You can set a default value. This value will be selected by default.
## File
```html
```
## Search / Select with search
We can use a component that emulates a `datalist` field but with the option to add values (known problem with `datalist` fields). For this we will use the `Select` component.
This component can use data that comes from an `array` or an `API`. Let's start with an example using an `array`. The first thing is to define the `array`:
```php
$array = [
[
'id' => 1, // key
'name' => 'Damián', // value
],
[
'id' => 2, // key
'name' => 'Daniel', // value
],
];
```
The component would look like this (using an `array`):
```html
```
Same case from an `URL`:
```html
```
**Select search / Datalist example:**
> **Important**: This component contains two input fields, both of which are submitted with the form. Using the example above they would be: `__country` and `country`. The first would send the value of `responseKey` and the second the value of `responseValue`.
### fromArray, fromUrl, resultKey, resultValue and comboboxFrom
Same behavior as select element.
### minChars
Minimum number of characters to start the search.
## Toggle
```html
```
## color
The allowed colors are: `primary`, `secondary`, `danger`, `warning` and `success`.
**Toogle button example:**
## Button
You can display different types of buttons on your form, which are easily configurable.
```html
```
### text
It will the text displayed in the button. In the future will be posible to add icons.
### type
You must define the button type. The supported one are: `submit` and `button`.
### color
The allowed colors are: `primary`, `secondary`, `danger`, `warning` and `success`.
### javascript
You can customize your buttons with javascript:
```html
```
It will render:
```html
...
```
> It is important that if you have to add single or double quotes into the javascript, you replace them with any of the following symbols:
- `
- `\\`
- `#`
For example:
```html
```
## Groups
It may be the case that you need to group several elements in a single container:
```html
```
### width
Same as the other elements.
### align
You can align the items inside the container using: `left`, `center` and `right`.
### position
The element can be in `vertical` or in `horizontal`. The default value is `horizontal`.
## Roadmap
- Combobox (alpinejs)
- Datetime (alpinejs, flatpickr)