213 lines
9.0 KiB
Markdown
213 lines
9.0 KiB
Markdown
# Fluig Form Attachment
|
|
|
|
Plugin JQuery para auxiliar no tratamento de anexos em formulários
|
|
de processo.
|
|
|
|
A gestão dos anexos de processo no Fluig não é uma tarefa fácil. Além da aba anexos não
|
|
permitir ordenação, o Fluig não permite, de maneira simples, vincular os anexos a campos
|
|
do formulário do processo, assim devemos confiar que os usuários vão colocar os anexos
|
|
corretamente na aba anexos e depois gastar tempo identificando cada anexo, pois usuários
|
|
dificilmente respeitarão alguma regra de nomenclatura.
|
|
|
|
Para permitir esse vínculo entre os campos do formulário e os anexos, o
|
|
[Sérgio Machado](https://www.linkedin.com/in/sergio-machado-analista-fluig/)
|
|
criou o [ComponenteAnexos](https://github.com/sergiomachadosilva/fluig-utils/tree/main/projetos/ComponenteAnexos),
|
|
que é uma biblioteca JS/CSS/HTML, permitindo um maior controle dos
|
|
anexos. Esse projeto do Sérgio serviu como base para a construção desse Plugin JQuery.
|
|
|
|
A intenção desse plugin é simplificar ainda mais o tratamento dos anexos em formulários
|
|
que estão abertos em um Processo.
|
|
|
|
## Atenção
|
|
|
|
Esse plugin não funciona na versão mobile dentro do aplicativo My Fluig.
|
|
|
|
Testado no Fluig 1.8.1 e 1.8.2. Quando lançar o Fluig 2.0 teremos que
|
|
rever o funcionamento do plugin.
|
|
|
|
Esse plugin está usando somente a "descrição" do anexo como vínculo entre
|
|
formulário e anexo. Ainda está em testes se isso é o suficiente ou se
|
|
o ideal seria ter o nome físico do arquivo salvo em algum lugar, assim
|
|
como o ComponenteAnexos do Sérgio Machado.
|
|
|
|
No Fluig 1.8.1 identifiquei um bug quando insere um anexo por vez e então remove
|
|
algum anexo. Nessa situação a tabela de anexos é esvaziada. Porém esse bug ocorre
|
|
mesmo quando usando a Aba de Anexos, sendo um bug do próprio Fluig e não do Plugin.
|
|
Esse bug ocorre somente na primeira atividade do processo, quando ainda não há ID
|
|
da Solicitação.
|
|
|
|
## Instalação
|
|
|
|
Basta adicionar o script `fluigFormAttachment.js` ou `fluigformAttachment.min.js` ao
|
|
seu formulário.
|
|
|
|
## Modo de usar
|
|
|
|
Ao carregar o plugin no seu formulário ele ocultará a Aba Anexos do Fluig, evitando que
|
|
insiram documentos não solicitados e, mais importante, removam anexos que já estão
|
|
vinculados a um campo do formulário.
|
|
|
|
### Básico
|
|
|
|
Basta ter um campo do tipo texto e instanciar o plugin para esse campo.
|
|
|
|
```html
|
|
<div class="form-group">
|
|
<label for="cnh">Teste 001</label>
|
|
<input type="text" class="form-control" readonly
|
|
name="cnh" id="cnh" data-filename="CNH" data-accept="image/*,.pdf"
|
|
>
|
|
</div>
|
|
```
|
|
|
|
É recomendável deixar o campo como `readonly`. O plugin fará isso automaticamente quando
|
|
instanciado no elemento, mas pode ser que algum usuário consiga editar o formulário fora
|
|
do processo e nesse caso o plugin não funcionará.
|
|
|
|
O atributo `data-filename` indica a "descrição" do anexo, que é o valor que aparece na Aba
|
|
Anexos. Esse nome será utilizado para vincular o campo do formulário ao anexo.
|
|
|
|
O atributo `data-accept` indica o tipo de arquivo permitido. Funciona exatamente como
|
|
o atributo `accept` do campo input file ([documentação](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept)).
|
|
|
|
Então no JavaScript basta executar:
|
|
|
|
```javascript
|
|
$("#cnh").fluigFormAttachment();
|
|
```
|
|
|
|
### Parâmetros
|
|
|
|
Ao instanciar o plugin para os elementos é possível passar um objeto com as seguintes
|
|
propriedades de configuração:
|
|
|
|
| Parâmetro | Tipo | Padrão | Descrição |
|
|
| --- | --- | --- | --- |
|
|
| **showActionButton** | boolean | `true` | Indica se deve exibir os botões de Ação (Upload ou Delete) |
|
|
| **filename** | string | `"Anexo"` | Nome/Descrição do Anexo. Caso exista o atributo `data-filename` no campo do formulário ele terá preferência. **Cuidado**: Não pode ter mais de um anexo com o mesmo Nome/Descrição. |
|
|
| **prefixName** | boolean\|string | `false` | Adiciona prefixo à descrição do anexo. Caso `true` criará um prefixo aleatório usando parte de um UUID. No caso de `string` a usará como prefixo fixo, adicionando `-` como separador. |
|
|
| **accept** | string | `"*"` | Funciona igual ao atributo accept do input file ([documentação](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept)). Caso exista o atributo `data-accept` no campo do formulário ele terá preferência. |
|
|
|
|
Se ao instanciar o Plugin o campo estiver **Desabilitado** ou o usuário não possuir permissão
|
|
de complemento no processo, o botão de Upload/Delete não será exibido, mesmo se o parâmetro
|
|
`showActionButton` estiver como `true`. Caso deseje exibir/ocultar o botão de ação dinamicamente
|
|
utilize os métodos `showActionButton` e `hideActionButton`.
|
|
|
|
A intenção da configuração `prefixName` é auxiliar nos casos de Tabela Pai Filho.
|
|
|
|
Lembre-se de tratar as situações nas quais o processo estiver somente em modo de
|
|
visualização e nos casos que os campos não devem permitir upload/delete dos
|
|
anexos.
|
|
|
|
Exemplos:
|
|
|
|
```javascript
|
|
$("#cnh").fluigFormAttachment({
|
|
showActionButton: false,
|
|
});
|
|
|
|
// Exibe os botões de visualização em todos os filhos já existentes da Pai Filho
|
|
// Pulamos a primeira TR por ser a base para gerar as demais filhas
|
|
$("#tabelaPaiFilho tbody tr:not(:first-child) .anexo")
|
|
.fluigFormAttachment({ showActionButton: false })
|
|
;
|
|
|
|
// Tabela Pai Filho - adiciona com prefixo automático para cada arquivo
|
|
$("#adicionar").on("click", function () {
|
|
const index = wdkAddChild("tabelaPaiFilho");
|
|
$(`#cnh___${index}`).fluigFormAttachment({
|
|
prefixName: true,
|
|
});
|
|
});
|
|
|
|
// Tabela Pai Filho com vários campos de anexo
|
|
$("#adicionar").on("click", function () {
|
|
const index = wdkAddChild("tabelaPaiFilho");
|
|
const tr = $(`#cnh___${index}`).closest("tr");
|
|
|
|
// A cada upload será criado um prefixo aleatório pra cada anexo
|
|
$(".anexos", tr).fluigFormAttachment({
|
|
prefixName: true,
|
|
});
|
|
});
|
|
|
|
// Tabela Pai Filho com vários campos de anexo e prefixo único pra linha
|
|
$("#adicionar").on("click", function () {
|
|
const index = wdkAddChild("tabelaPaiFilho");
|
|
const tr = $(`#cnh___${index}`).closest("tr");
|
|
|
|
// A cada upload usará o mesmo prefixo para todos os anexos da linha
|
|
$(".anexos", tr).fluigFormAttachment({
|
|
prefixName: FLUIGC.utilities.randomUUID().substring(0, 8),
|
|
});
|
|
});
|
|
```
|
|
|
|
### Métodos
|
|
|
|
É possível executar alguns métodos do Plugin para manipular os anexos. Para
|
|
executar um método basta chamar o plugin no campo indicando passando o nome
|
|
do método ao invés do objeto de parâmetros.
|
|
|
|
Os seguintes métodos estão disponíveis:
|
|
|
|
| Método | Executa em | Parâmetros | Retorno | Descrição |
|
|
| --- | --- | --- | --- | --- |
|
|
| **hasAttachment** | Primeiro Elemento | - | `boolean` | Indica se o campo possuí anexo (tem descrição e o anexo está na tabela de anexos) |
|
|
| **isValid** | Primeiro Elemento | - | `boolean` | Indica se o campo está válido. Caso ele possua um valor (foi feito upload do anexo), mas o anexo não está na tabela de anexos, indicará campo inválido. Este método é executado em um único campo |
|
|
| **deleteAttachment** | Todos Elementos | - | `JQuery` | Remove o anexo do campo. Útil para quando excluir uma linha de uma tabela Pai Filho |
|
|
| **showActionButton** | Todos Elementos | - | `JQuery` | Exibe o botão de ação |
|
|
| **hideActionButton** | Todos Elementos | - | `JQuery` | Oculta o botão de ação |
|
|
| **prefixName** | Todos Elementos | string\|boolean | `JQuery` | Altera o prefixName para os elementos |
|
|
| **filename** | Todos Elementos | string, string\|boolean | `JQuery` | Altera o filename configurado para os elementos. Pode passar, como segundo parâmetro, o prefixName |
|
|
|
|
Exemplos:
|
|
|
|
```javascript
|
|
if ($("#cnh").fluigFormAttachment("hasAttachment")) {
|
|
// Exemplo: habilitar outro campo de preenchimento
|
|
}
|
|
|
|
function beforeSendValidate(numState, nextState) {
|
|
if (!$("#cnh").fluigFormAttachment("isValid")) {
|
|
throw "O Anexo da CNH não foi enviado corretamente. Remova-o e envie novamente";
|
|
}
|
|
}
|
|
|
|
// Removendo anexos da Pai Filho ao excluir linha
|
|
$("#tabelaPaiFilho").on("click", ".removeItem", function() {
|
|
$(".anexos", $(this).closest("tr")).fluigFormAttachment("deleteAttachment");
|
|
fnWdkRemoveChild(this);
|
|
});
|
|
|
|
// Habilitando/Desabilitando a ação de acordo com o preenchimento de um campo
|
|
$("#descricao").on("change", function () {
|
|
this.value = this.value.trim();
|
|
|
|
if (!this.value.length) {
|
|
$("#anexo").fluigFormAttachment("hideActionButton");
|
|
return;
|
|
}
|
|
|
|
// Trocando o filename pra ser dinâmico com a descrição
|
|
// Caso exista uma descrição igual nos anexos exibirá erro
|
|
// no momento de selecionar o arquivo.
|
|
$("#anexo")
|
|
.data("filename", this.value)
|
|
.fluigFormAttachment("showActionButton")
|
|
;
|
|
|
|
// Altera o filename igual ao exemplo anterior
|
|
$("#anexo").fluigFormAttachment("filename", this.value).fluigFormAttachment("showActionButton");
|
|
|
|
// Altera prefixName no componente
|
|
$("#anexo").fluigFormAttachment("prefixName", true);
|
|
// ou
|
|
$("#anexo").fluigFormAttachment("prefixName", "novoprefixo");
|
|
});
|
|
```
|
|
|
|
## Contribuições
|
|
|
|
Sinta-se à vontade para indicar bugs e sugestões abrindo issues.
|