# mre-select-autocomplete

`<mre-select-autocomplete>` é um componente composto inicialmente por um botão que quando clicado exibe um dropdown
     com items para seleção e um input para pesquisa dos mesmos.

## Instalação

- Adicionar o arquivo CSS no HTML

```html
<link rel="stylesheet" href="/vendor/mre-select-autocomplete/assets/css/mre-select-autocomplete.css">
```
- Adicionar o arquivo JS no HTML

```html
<link rel="stylesheet" href="/vendor/mre-select-autocomplete/src/mre-select-autocomplete.js">
```
- Injetar o módulo na aplicação

```javascript
angular.module('seu.module', [
     'mre.selectAutocomplete'
]);
```


## Utilização
###single-select & multi-select
O componente possibilita em sua listagem a seleção única ou multipla de itens através da especificação dos atributos 
`single-select` ou `multi-select`, cujo valor deve ser a model que será utilizada para armazenar os itens selecionados
pelo usuário.
 
**single-select:** Os itens são exibidos com *radio button* para seleção e sua model deve ser do tipo `object`
 
**multi-select:** Os itens são exibidos com *checkbox* para seleção e sua model deve ser do tipo `array`
 
### on-click-item
Para o atributo on-click-item, deve-se passar a `function` a ser chamado no click de um item **sem os `()`**, pois o componente
passará para essa função informações sobre o item selecionado como parâmetros, e esses parâmetros mudam conforme o tipo 
de select selecionado.
 
**single-select:** a função receberá os parâmetros (item, event);

**multi-select:** a função receberá os parâmetros (item, checked, event);

| Param             | Descrição     |
| ----------------- | ------------- |
| item              | O item clicado |
| checked           | Apenas no caso de **multi-select**, retorna *true* e *false* para o status de seleção do checkbox |
| event             | O evento do click no radio/checkbox |

### Pesquisa em serviço através de promise
Para listagem de items o componente deve receber no atributo `items` um `array` ou uma `promise` cujo retorno seja um array,
caso o retorno da promise seja um objeto, pode-se usar o atributo `obj-path` para especificar o caminho até chegar no array

Quando se for listar itens retornados de um resource, a declaração em `items`
(no exemplo:`pesquisaResultados()`) deve retornar a promise desta, o que é feito acrescentado `.$promise` ao final da função 
da resource, conforme o exemplo abaixo.

#### Javascript
```javascript
function AppController($scope, ServicoResource) {
    
    vm.modelTextoPesquisa = '';
    
    vm.pesquisaResultados = function() {
        return ServicoResource.get({param: vm.modelTextoPesquisa}, function (response) {
        }, function (error) {
            Materialize.toast(error.message);
        }).$promise;
    };
}
```

#### HTML
```html
<mre-select-autocomplete
  search-text-model="Controller.modelTextoPesquisa"
  placeholder="Encontre postos..."
  button-label="Postos"
  items="Controller.pesquisaResultados()"
  item-text="noAtributoTextoDoItem"
  item-value="idUnicoAtributoDoItem"
  not-found-text="Sem resultados."
  multi-select="Controller.modelItemsSelecionados"
  obj-path="_embedded.unidade_administrativa"
  min-length="3"
  on-click-item="Controller">
</mre-select-autocomplete>
 ```
 
### Pesquisa através de array fixo

Quando a lista de elementos for fixa, pode-se passar o array diretamente para o componente, caso essa lista venha de um 
serviço do back-end, deve-se utilizar o atributo `force-loading` para controlar o estado de loading do componente enquanto 
a requisação é feita.

#### Javascript
```javascript
function AppController($scope, ServicoResource) {
    
    vm.modelTextoPesquisa = '';
    
    vm.pesquisaResultados = function() {
        
        vm.isServicoLoading = true;
        
        ServicoResource.get({param: vm.modelTextoPesquisa}, function (response) {
            
            vm.arrListaFixa = response._embedded.lista;
            vm.isServicoLoading = false;
            
        }, function (error) {
            Materialize.toast(error.message);
            vm.isServicoLoading = false;
        });
    };
}
```

#### HTML
```html
<mre-select-autocomplete
  search-text-model="Controller.modelTextoPesquisa"
  placeholder="Encontre unidades..."
  button-label="Unidades"
  items="Controller.arrListaFixa"
  item-text="noAtributoTextoDoItem"
  item-value="idUnicoAtributoDoItem"
  multi-select="Controller.modelItemsSelecionados"
  force-loading="Controller.isServicoLoading"
  delay="0">
</mre-select-autocomplete>

Como trata-se de uma lista fixa, não existe necessidade do componente esperar um tempo para realizar a pesquisa,
deste modo especifica-se o atributo "delay" para "0" para os resultados serem refletidos imediatamente.
 ```
 
 
### Arguments

| Param             | Tipo          | Descrição     |
| ----------------- | ------------- | ------------- |
| items             | expression    | Array ou promise dos items a serem exibidos, pode ser uma função que retorna os resultados de forma sincrona ou assincrona (por Promise) |
| obj-path          | string        | Caso a promise retorne um objeto, pode-se especificar o caminho do objeto até o array dos items a serem listados |
| search-text-model | string        | Uma model utilizada para armazenar o texto de busca. |
| single-select     | object        | Especifica que apenas um item da listagem poderá ser selecionado, e onde é especificada uma model para armazenar o objeto do resultado selecionado |
| multi-select      | array         | Especifica que multiplos itens da listagem poderão ser selecionados, e onde é especificada uma model para armazenar o array dos resultados selecionados |
| button-label      | string        | Texto que será exibido dentro do botão do componente |
| item-text         | string        | O nome do atributo do objeto que contém o texto a ser exibido na label ao lado do checkbox/radio |
| item-value        | string        | O nome do atributo do objeto que contém um valor único do objeto selecionado |
| input-name        | string        | O atributo name do elemento input |
| input-id          | string        | O ID do elemento input |
| placeholder       | string        | Texto do Placeholder que será aplicado no input |
| not-found-text    | string        | Texto customizado exibido quando a pesquisa não retornar pelo menos um item |
| delay             | number        | Determina a quantidade de tempo (em milliseconds) para esperar antes de buscar resultados |
| force-loading     | boolean       | Força o status de loading do componente |
| min-length        | number        | Determina o número minimo de caracteres do texto para o autocomplete fazer sugestões |
| on-click-item     | expression    | Uma função que será executada quando um item for clicado pelo usuário, deve-se passar a `function` a ser chamado no click de um item **sem os `()`**. <br> **single-select:** a função receberá os parâmetros (item, event); <br>**multi-select:** a função receberá os parâmetros (item, checked, event); |
| on-clear-all      | function      | Uma função que será executada após o "Limpar itens selecionados" for clicado e o componente limpar a model de itens selecionados |
| on-click-button   | function      | Uma função que será executada quando o botão do componente for clicado |