zeev-utils

Zeev Utils

Coleção não-oficial de funções utilitárias para interagir facilmente com formulários no Zeev

Instalação | Como Utilizar | Configuração | Funções | Roadmap

Instalação

Usar via NPM

npm install zeev-utils

# ou com yarn

yarn add zeev-utils

Usar via CDN

Apenas adicione a script tag ao cabeçalho do processe e consuma as funções através do namespace Utils.funcao

<script src="https://cdn.jsdelivr.net/gh/pedbernardo/zeev-utils@latest/dist/zeev-utils.js"></script>

<!-- ou minificado -->

<script src="https://cdn.jsdelivr.net/gh/pedbernardo/zeev-utils@latest/dist/zeev-utils.min.js"></script>

Como Utilizar

// importe todas as funções com namespace
import Utils from 'zeev-utils'

Utils.showField('meuCampo')

// importe as funções separadamente
import { showField, hideField } from 'zeev-utils'

showField('meuCampo')

Utilizando via script tag e CDN

// todas as funções estarão disponíveis através do namespace `Utils`
// globalmente, você inclusive pode testar as funções diretamente
// no console do seu navegador

Utils.showField('meuCampo')
Utils.hideField('meuCampo')

Configuração

Configuração Padrão

const config = {
  container: 'tr',
  hideClass: 'hidden',
  toggleRequiredClass: false,
  requiredClass: 'execute-required',
  requiredAttribute: 'data-was-required'
}

Construtor

Como modificar os parâmetros padrão?

Ao importar a biblioteca (seja através da CDN ou NPM) ela irá dispor das funções utilitárias com a configuração padrão acima. Embora os métodos permitam que a configuração seja redefinida nos parâmetros, você pode utilizar o construtor para criar uma nova instância com os parâmetros desejados de forma fixa.

setup

Cria uma nova instância de Utils com os parâmetros padrão que desejar

Utils.setup( Object )

Exemplo de uso

const UtilsForm = Utils.setup({
  container: '.form-group',
  hideClass: 'is-hidden',
  requiredClass: 'is-required',
})

UtilsForm.hideField(document.querySelector('[xname=inpfieldId]'))

Funções

Visibility

• showField
• hideField
• showGroup
• hideGroup

Requirement

• isRequired
• addRequired
• removeRequired

Field

• getField
• getFieldContainer
• getFieldValue
• clearField
• onFileChange

showField

Exibe um campo de formulário e recoloca sua obrigatoriedade (caso possua)

Utils.showField( string | HTMLElement | Node, Object [optional] )

Exemplo de uso

Utils.showField('meuCampoId')
Utils.showField(document.querySelector('[xname=inpmeuCampoId]'), { container: '.group' })

hideField

Oculta um campo de formulário, limpa o seu valor e remove sua obrigatoriedade (caso possua)

Utils.hideField( string | HTMLElement | Node, Object [optional] )

Exemplo de uso

Utils.hideField('meuCampoId')
Utils.hideField(document.querySelector('[xname=inpmeuCampoId]'), { container: '.group' })

showGroup

Exibe um conjunto de campos de formulário a partir do seu container e recoloca sua obrigatoriedade (caso possuam)

Utils.showGroup( string | HTMLElement | Node, Object [optional] )

Exemplo de uso

Utils.showGroup('.meu-grupo-de-campos')
Utils.showGroup(document.querySelector('.meu-grupo-de-campos'))

hideGroup

Oculta um conjunto de campos de formulário a partir do seu container, limpando todos os valores e removendo a obrigatoriedade (caso possuam)

Utils.hideGroup( string | HTMLElement | Node, Object [optional] )

Exemplo de uso

Utils.hideGroup('.meu-grupo-de-campos')
Utils.hideGroup(document.querySelector('.meu-grupo-de-campos'))

isRequired

Verifica se um campo de formulário é obrigatório, observando também a propriedade especial data-was-required em campos obrigatórios ocultados, ainda que estejam com a propriedade required=N

Utils.isRequired( string | HTMLElement | Node)

Exemplo de uso

Utils.isRequired('meuCampoId')
Utils.isRequired(document.querySelector('[xname=inpmeuCampoId]'))

addRequired

Adiciona obrigatoriedade a um campo de formulário

Utils.showField( string | HTMLElement | Node)

Exemplo de uso

Utils.addRequired('meuCampoId')
Utils.addRequired(document.querySelector('[xname=inpmeuCampoId]'))

removeRequired

Remove obrigatoriedade de um campo de formulário

Utils.showField( string | HTMLElement | Node)

Exemplo de uso

Utils.removeRequired('meuCampoId')
Utils.removeRequired(document.querySelector('[xname=inpmeuCampoId]'))

getField

Busca campos de formulário do Zeev, podendo ser a partir do seu identificador, com ou sem o prefixo inp

Utils.getField( string | HTMLElement | Node, Object [optional] )

Exemplo de uso

Utils.getField('meuCampoId')
Utils.getField('inpmeuCampoId')
Utils.getField(document.querySelector('[xname=inpmeuCampoId]'))

// retorna array mesmo que seja apenas um campo
Utils.getField('fieldId', { returnArray: true })

getFieldContainer

Busca o container de um campo de formulário do Zeev

Utils.getFieldContainer( string | HTMLElement | Node, String)

Exemplo de uso

Utils.getFieldContainer('fieldId', '.form-group')
Utils.getFieldContainer(document.querySelector('[xname=inpfieldId]'), '.form-group')

getFieldValue

Retorna o(s) valor(es) selecionado(s) de um campo de formulário

Utils.getFieldValue( string | HTMLElement | Node)

Exemplo de uso

Utils.getFieldValue('meuCampoTexto')                // 'valor do campo' ou ''
Utils.getFieldValue('meuCampoCaixaSelecao')         // 'valor do campo' ou ''
Utils.getFieldValue('meuCampoAreaTexto')            // 'valor do campo' ou ''
Utils.getFieldValue('meuCampoHidden')               // 'valor do campo' ou ''
Utils.getFieldValue('meuCampoArquivo')              // 'url pública do arquivo' ou ''
Utils.getFieldValue('meuCampoRadio')                // 'valor da opção selecionada'
Utils.getFieldValue('meuCampoCheckbox')             // ['opção A selecionada', 'opção B selecionada'] ou []
Utils.getFieldValue('meuCampoTextoEmMultivalorada') // ['valor linha 1', 'valor linha 2'] ou ['', '']

clearField

Limpa os valores de um campo de formulário

Utils.showField( string | HTMLElement | Node)

Exemplo de uso

Utils.clearField('meuCampoId')
Utils.clearField(document.querySelector('[xname=inpmeuCampoId]'))

onFileChange

Trigger disparado quando um campo do tipo Arquivo é modificado

Utils.onFileChange( string | HTMLElement | Node, function [callback] )

Callbacks

Adição de Arquivo Callback( string [filepath], HTMLElement [delete button] )
Remoção de Arquivo Callback( null )

Exemplo de uso

Utils.onFileChange('meuCampoId', (filepath, deleteBtn) => {
  console.log({ filepath, deleteBtn })
})

Roadmap

Versão 1.0.0

• Alterar definição de tipos de JSDocs para TypeScript
• Finalizar 100% de cobertura de testes para funções públicas
• Construir documentação utilizando Vitepress (mockups finalizados)
• Automatizar build com uso de Github Actions