# InputKey
<style>
    img {
        max-width: 100%;
    }
    pre {
        background-color: #F5F5F5;
        padding: .5rem;
    }
</style>



## Definición

Archivo: `induxsoft.controls.js`

Es un componente que facilita le facilita al usuario la busqueda y selección de datos de una manera clara y amigable.

<img src="/es/api/web-components/img/inputkey-demo-01.jpeg">



## Ejemplos

El atributo `data-source` permite establecer el listado de los datos mediante una solicitud GET.
```html
<input-key
    id="usuario"
    name="usuario"
    data-key="id"
    data-search="username"
    data-text="name"
    data-source="https://jsonplaceholder.typicode.com/users/"
    columns="username,name,email,phone"
    colcaptions="Usuario,Nombre,Correo,Telefono">
</input-key>
```

El atributo `data-source-array` permite establecer el listado de los datos mediante una cadena que representa un objeto JSON.
```html
<input-key
    id="usuario"
    name="usuario"
    data-key="id"
    data-search="codigo"
    data-text="nombre"
    data-source-array='[
        {"id":1, "codigo":"001", "nombre":"Bob"},
        {"id":2, "codigo":"002", "nombre":"Katelynn"},
        {"id":3, "codigo":"003", "nombre":"Larry"}
    ]'
    columns="codigo,nombre"
    colcaptions="Código,Nombre">
</input-key>
```

Implementar botones personalizados.
```html
<input-key
    ...
    buttons='[
        {"id":"btn-ext-1", "content":"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"12\" height=\"12\" fill=\"currentColor\" class=\"bi bi-plus-lg\" viewBox=\"0 0 16 16\"><path fill-rule=\"evenodd\" d=\"M8 2a.5.5 0 0 1 .5.5v5h5a.5.5 0 0 1 0 1h-5v5a.5.5 0 0 1-1 0v-5h-5a.5.5 0 0 1 0-1h5v-5A.5.5 0 0 1 8 2Z\"/></svg>"},
        {"id":"btn-ext-2", "content":"<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"12\" height=\"12\" fill=\"currentColor\" class=\"bi bi-pencil-fill\" viewBox=\"0 0 16 16\"><path d=\"M12.854.146a.5.5 0 0 0-.707 0L10.5 1.793 14.207 5.5l1.647-1.646a.5.5 0 0 0 0-.708l-3-3zm.646 6.061L9.793 2.5 3.293 9H3.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.5h.5a.5.5 0 0 1 .5.5v.207l6.5-6.5zm-7.468 7.468A.5.5 0 0 1 6 13.5V13h-.5a.5.5 0 0 1-.5-.5V12h-.5a.5.5 0 0 1-.5-.5V11h-.5a.5.5 0 0 1-.5-.5V10h-.5a.499.499 0 0 1-.175-.032l-.179.178a.5.5 0 0 0-.11.168l-2 5a.5.5 0 0 0 .65.65l5-2a.5.5 0 0 0 .168-.11l.178-.178z\"/></svg>"}
    ]'>
</input-key>
```

**Ejemplos de uso con JavaScript**

Obtener el elemento seleccionado de la tabla de datos.
```js
const input = document.getElementById("usuario");

let item = input.getValue();
console.log(item); // Salida esperada: {id:"", codigo:"", nombre:""}
```

Buscar un elemento dentro de la tabla de datos.
```js
const input = document.getElementById("usuario");

let found = input.findValue("2");
console.log(found); // Salida esperada: {id:2, codigo:"002", nombre:"Katelynn"}
```

Establecer valor del componente.
```js
const input = document.getElementById("usuario");

let value = {id:1, codigo:"001", nombre:"Bob"}
input.setValue(value);
```

Limpiar elemento seleccionado.
```js
const input = document.getElementById("usuario");
input.clear();
```

Establecer evento `change` al componente.
```js
const input = document.getElementById("usuario");

input.addEventListener("change", (data) => {
    /**
     * data: (array) Objeto con la información seleccionada/establecida.
    */
    
    // implementación...
});
```

Establecer propiedad `change_event`. Se dispara cuando se establece un nuevo valor al componente.
```js
const input = document.getElementById("usuario");

input.change_event = (data) => {
    /**
     * data: (array) Objeto con la información seleccionada/establecida.
    */
    
    // implementación...
}
```

Establecer propiedad `onBeforeSearch`. Se dispara antes de realizar una peticion GET.
```js
const input = document.getElementById("usuario");

input.onBeforeSearch = (surl) => {
    /**
     * surl: (string) Valor del atributo `data-source`.
    */
    
    // implementación...
    return surl; // ¡Es necesario responder con una url!
}
```

Implementar acciones a los botones personalizados.
```js
document.addEventListener("DOMContentLoaded", () => {
    const btn_ext_1 = document.getElementById("btn-ext-1");
    const btn_ext_2 = document.getElementById("btn-ext-2");

    btn_ext_1.addEventListener("click", (e) => {
        /* implementación */
    });
    btn_ext_2.addEventListener("click", (e) => {
        /* implementación */
    });
});
```



## Comentarios

El componente InputKey ofrece una interfaz que facilita la búsqueda y selección de datos al usuario, en donde los siguientes atributos deben corresponder a propiedades existentes en el array de objetos establecidos en `data-source-array` o los obtenidos desde `data-source`.

- data-key
- data-search
- data-text
- columns
- colcaptios

Al realizar una solicitud GET, el componente comprueba tres macros en la url:

- @search: (opcional) Valor del parámetro a buscar establecido en el campo de búsqueda (data-search) del componente.
- @key: (opcional) Valor "data-key" del registro seleccionado.
- @text: (opcional) Descripción "data-text" del registro seleccionado.



## Atributos

#### id (opcional)
Identificador del componente, este Puede ser usado para acceder facilmente al componente mediante javascript.

Tipo: `string`, Predeterminado: `""`
```html
<input-key id="usuario">
```

#### name (opcional)
Nombre que sera tomado por el navegador para la carga útil.

Tipo: `string`, Predeterminado: `""`
```html
<input-key name="usuario">
```

#### data-key (requerido)
Establece el campo a guardar al seleccionar un registro.

Tipo: `string`

```html
<input-key data-key="id">
```

#### data-search (requerido)
Establece el campo a considerar en la búsqueda de un registro.

Tipo: `string`
```html
<input-key data-search="codigo">
```

#### data-text (opcional)
Establece el campo a mostrar en la descripción del registro seleccionado.

Tipo: `string`, Predeterminado: `""`
```html
<input-key can-drag="true">
```

#### data-value (opcional)
Esteblece el valor inicial del componente.

Tipo: `object`, Predeterminado: `""`
```html
<input-key data-value='{"id":1, "codigo":"001", "nombre":"Bob"}'>
```

#### data-source-array (opcional)
Establece los datos a usar en la selección de registros

Tipo: `array`, Predeterminado: `""`
```html
<input-key data-source-array='[
    {"id":1, "codigo":"001", "nombre":"Bob"},
    {"id":2, "codigo":"002", "nombre":"Katelynn"},
    {"id":3, "codigo":"003", "nombre":"Larry"}
]'>
```

#### data-source (opcional)
Establece el endpoint para la obtención de registros.

Tipo: `string`, Predeterminado: `""`
```html
<input-key data-source="https://host/users/?search=@search">
```

#### add-url (opcional)
Establece el endpoint para la adición de nuevos registros.

Tipo: `string`, Predeterminado: `""`
```html
<input-key add-url="https://host/users/_new/">
```

#### edit-url (opcional)
Establece el endpoint para la edición del registro seleccionado.

Tipo: `string`, Predeterminado: `""`
```html
<input-key edit-url="https://host/users/@key/">
```

#### columns (opcional)
Establece los campos a mostrar en la tabla de resultados de búsqueda.

Tipo: `string`, Predeterminado: `"*"`
```html
<input-key columns="codigo,nombre">
```

#### colcaptions (opcional)
Establece los encabezados de la tabla de resultados de búsqueda.

Tipo: `string`, Predeterminado: `"*"`
```html
<input-key colcaptions="Código,Nombre">
```

#### search-value (opcional)
Texto a mostrar por defecto en el campo de búsqueda.

Tipo: `string`, Predeterminado: `""`
```html
<input-key search-value="">
```

#### text-value (opcional)
Texto a mostrar por defecto en el campo de descripción.

Tipo: `string`, Predeterminado: `""`
```html
<input-key text-value="">
```

#### box-title-text (opcional)
Texto a mostrar en el título del buscador.

Tipo: `string`, Predeterminado: `"Seleccione un registro"`
```html
<input-key box-title-text="Seleccione un usuario">
```

#### box-placeholder-text (opcional)
Texto a mostrar en el placeholder del buscador.

Tipo: `string`, Predeterminado: `"Buscar..."`
```html
<input-key box-placeholder-text="Buscar usuario">
```

#### box-nodata-text (opcional)
Texto a mostrar cuando no haya datos para mostrar.

Tipo: `string`, Predeterminado: `"Sin registros"`
```html
<input-key box-nodata-text="No se encontraron usuarios">
```

#### buttons (opcional)
Una cadena que representa un objeto JSON que permite establecer botones extras personalizados.

Tipo: `array`, Predeterminado: `""`
```html
<input-key buttons='[
    {"id":"", content:""},
    ...
]'>
```

#### disabled (opcional)
Desabilita los controles del componente.

Tipo: `bool`, Predeterminado: `false`
```html
<input-key disabled="false">
```

#### required (opcional)
Establece que el campo tenga datos antes de enviarse el formulario.

Tipo: `bool`, Predeterminado: `false`
```html
<input-key required="true">
```

#### hidden-input (opcional)
Define si se crea un elemento input oculto fuera el web component para ser tomado por formularios o selectores.

Tipo: `bool`, Predeterminado: `true`
```html
<input-key hidden-input="false">
```

#### hide-searcher (opcional)
Define si sé el control de búsqueda se oculta, siendo visible únicamente el botón y el control de descripción.

Tipo: `bool`, Predeterminado: `false`
```html
<input-key hide-searcher="false">
```

#### control-styles (opcional)
Establece los estilos personalizados que se le aplicarán al control.

Tipo: `string`, Predeterminado: `""`
```html
<input-key control-styles="">
```



## Propiedades

- `data`: (array) Lista de objetos que establece los datos a usar en la selección de registros.
- `searchData`: (string) Establece el campo a considerar en la búsqueda de un registro.
- `columns`: (string) Establece los campos a mostrar en la tabla de resultados de búsqueda.
- `colcaptions`: (string) Establece los encabezados de la tabla de resultados de búsqueda.
- `change_event`: (function) Se dispara cuando se establece un nuevo valor al componente.
- `onBeforeSearch`: (function) Se dispara antes de realizar una peticion GET.



## Métodos

#### findValue

Retorna un elemento dentro del objeto de datos que coincida con el valor especificado establecido en la propiedad searchData y el identificador proporcionado.

**Parámetros**
- `string` **id** Cadena con el valor a buscar.

```js
findValue(id): array{}
```

#### getValue

Retorna el objeto seleccionado en la tabla de datos.

```js
getValue(): array{} | null
```

#### setValue

Establece el valor del control.

**Parámetros:**
- `array` **value** Objeto con la información a establecer.

```js
setValue(value): void
```

#### clear

Limpia la información del objeto seleccionado y los controles del componente.

```js
clear(): void
```



## Eventos

#### change

Sobrescribe el escuchador de eventos del componente con el definido por el usuario en la propiedad `change_event`.

```js
InputKey.addEventListener("change", function(data){/*...*/})
```