vesperabr / laravel-form-components
Componentes Blade para desenvolvimento rápido de formulários
Requires
- php: >=7.3
- illuminate/support: ^8
README
Conjunto de componentes Blade para desenvolvimento rápido de formulários com suporte ao Monalisa e em breve a outros frameworks CSS.
Funcionalidades
- Componentes para form, input, textarea, select, multi-select, checkbox e radio.
- Gerenciamento automático do Form Method Spoofing
- Gerenciamento automático do CSRF Protection
- Suporte ao Monalisa e em breve outros frameworks CSS.
- Atribuição automática de valores.
- Re-população de valores via old input.
- Classes dos componentes e views totalmente customizáveis.
Requisitos
- PHP 7.3
- Laravel 7
Instalação
Você pode instalar este pacote pelo composer:
composer require vesperabr/laravel-form-components
Exemplo rápido
<x-form> <x-input name="nome" label="Nome" /> <x-input type="cpf" name="cpf" label="CPF" /> <x-input type="email" name="email" label="E-mail" /> <x-input type="password" name="senha" label="Senha" /> <button>Enviar</button> </x-form>
Componentes
Form
Por padrão o componente <x-form>
utiliza o verbo GET no atributo method
.
Você pode informar qualquer outro verbo e o componente irá lidar automaticamente com o method spoofing e controle de CSRF para você.
<!-- Utilizando --> <x-form method="PUT"> ... </x-form> <!-- Irá gerar: --> <form method="POST"> <input type="hidden" name="_method" value="PUT"> <input type="hidden" name="_token" value="xxx"> </form>
Você pode informar normalmente qualquer outro atributo da tag <form>
, como por exemplo action
, class
, id
, etc.
Você pode informar também o atributo multipart
, que irá configurar automaticamente o formulário para enviar arquivos. Exemplo:
<x-form method="POST" multipart> ... </x-form>
Label
Na maioria dos componetes deste pacote você pode informar o atributo label
, com isto o componente irá renderizar uma tag <label>
com o valor especificado.
Input
Por padrão o componente <x-input />
gera uma tag <input />
com o atributo type="text"
, mas você pode informar qualquer outro type
padrão do HTML como por exemplo password, email, tel, url, number, etc.
Você pode informar outros atributos como required
, placeholder
, class
, id
, etc.
<x-input type="email" label="Digite seu email" name="email" required />
Tipos especiais
O componente <x-input />
aceita alguns tipos especiais como cpf
, cnpj
, cpfcnpj
, cep
, float
e money
. Isso irá aplicar máscaras de formatação ao campo.
<x-input type="cpf" name="cpf" placeholder="Digite seu CPF" />
Inserindo valores antes e depois do campo
Você pode informar também os atributos append
e prepend
. Isto irá exibir valores antes ou depois do campo.
<x-input type="float" name="preco" prepend="R$" /> <x-input name="subdominio" append=".vespera.com.br" />
Textarea
Este componente é bem parecido com o <x-input />
, com exceção ao suporte de máscaras e valores antes e depois.
<x-textarea label="Observações" name="observacoes" />
Select
O componente <x-select />
precisa que você informe o atributo options
para que ele popule os valores que o usuário pode escolher. Este atributo deve ser um array no formato chave => valor.
$paises = [ 'br' => 'Brasil', 'us' => 'Estados Unidos', 'jp' => 'Japão', ];
<x-select name="pais" :options="$paises" />
Você pode definir qual(is) o(s) valor(es) que deverão vir selecionado(s) através do atributo selected
. Se você adicionar o atributo multiple
ao componente, lembre-se de passar um array simples com as chaves que deverão ser selecionadas.
<x-select name="pais" :options="$paises" selected="['br', 'jp']" multiple />
Checkbox
Você pode criar um conjunto de checkboxes utilizando o componente <x-checkboxes />
. Assim como o componente <x-select />
você deve informar o atributo options
contendo um array no formato chave => valor.
<x-checkboxes name="paises[]" :options="$paises" />
Você pode informar os valores que devem vir selecionados através do atributo selected
que pode ser uma string ou um array contendo as chaves que devem ser selecionadas.
<x-checkboxes name="paises[]" :options="$paises" :selected="['br', 'jp']" />
Há também o componente <x-checkbox />
que irá criar um único checkbox. Ele deve ser usado para criar campos de aceite ou ativo/inativo.
Você pode informar o atributo default
que irá prover um input hidden com o valor padrão caso o campo não seja selecionado.
<x-checkbox name="ativo" value="sim" default="nao" label="Usuário ativo?" />
Radio
O componente <x-radios />
prove um conjuto de radios. Você deve informar o atributo options
contendo um array no formato chave => valor.
<x-radios name="paises" :options="$paises" />
Para definir o valor que deve vir selecionado, utilize o atributo selected
.
<x-radios name="paises" :options="$paises" selected="br" />
Buttons
O componente <x-buttons />
gera os botões para controle do formulário.
Você pode informar o atributo submit
que será o texto do botão de envio do formulário.
<x-buttons submit="Enviar formulário" />
Se você informar também o atributo cancel-url
, o componente irá exibir um link cancelar apontando para o valor informado.
<x-buttons submit="Enviar formulário" cancel-url="http://google.com" />
Você pode informar também o atributo loader
, que exibe um loader ao clicar no botão de enviar. Somente a presença deste atributo já habilita loader. Se você definir um valor para o atributo, o texto do botão será alterado enquanto ele estiver com o loader ativo.
<x-buttons submit="Salvar" loader /> <x-buttons submit="Salvar" loader="Salvando..." />
Slots
Os componentes <x-input>
, <x-checkbox>
, <x-checkboxes>
, <x-radios>
, <x-select>
e <x-textarea>
permitem que você informe conteúdos adicionais, os chamados Slots. Por exemplo:
<x-input type="email" label="Digite seu e-mail"> <p>Fique tranquilo, também não gostamos de spam!</p> </x-input>
Atribuição de valores
Como visto, você pode definir os valores dos campos atráves do atributo value
(para o componente <x-input />
) ou através do atributo selected
(para os componentes <x-select />
, <x-radios />
, <x-checkboxes />
e <x-checkbox />
).
Model binding
Ao invés de definir os atributos value
e selected
, há também a possibilidade de pegar o valor de um campo automaticamente de um model Eloquent ou de um array associativo. Basta utilizar o atributo :bind
.
No exemplo abaixo o componente irá procurar na variável $usuario
(que deve ser uma instância de um model Eloquent ou um array associativo) a propriedade nome
que foi definida através do atributo name
. Neste caso o valor do campo seria o valor de $usuario->nome
.
<x-input name="nome" :bind="$usuario" />
Você pode fazer o bind em vários campos de uma só vez informando o atributo bind
no componente <x-form>
ou utilizando as diretivas @bind
e @endbind
.
<x-form :bind="$usuario"> <x-input name="nome" /> <x-input name="email" /> </x-form>
<x-form> @bind($usuario) <x-input name="nome" /> <x-input name="email" /> @endbind </x-form>
Você pode inclusive intercalar bindings.
<x-form :bind="$usuario"> <x-input name="nome" /> @bind($perfilDoUsuario) <x-textarea name="descricao"> @endbind </x-form>
Você pode também desabilitar o bind definindo o atributo :bind
ou a diretiva @bind
como false
.
<x-form :bind="$usuario"> <x-input name="nome" /> <x-input name="email" :bind="false" /> </x-form>
Old input data
Quando ocorre um erro de validação e o Laravel redireciona você de volta ao formulário, os campos continuarão com os valores digitados. Isto irá sempre sobrescrever qualquer valor padrão.
Customização
Você pode publicar o arquivo de configuração e também as views com o seguinte comando:
php artisan vendor:publish --provider="Vespera\LaravelFormComponents\ServiceProvider"
O arquivo de configuração form-components.php
estará disponível na pasta config
e as views serão publicadas na pasta resources/views/vendor/form-components
.
No arquivo de configuração você pode definir qual framework CSS você irá utilizar e também a localização de cada view utilizada em cada componente.
Créditos
- Este pacote é inspirado no ótimo trabalho do Pascal Baljet.