Cfa-Ditto

Libreria que concentra en un unico componenente la arquittectura de pantalla: Filtros + Paginado + Tabla de Resultados + Acciones,

Ejemplo de uso. Instalacion: en package.json

"dependencies": {
....
"cfa-ditto": "1.0.5",
....
}

Ejemplo de implementación

import { DittoFilter } from 'cfa-ditto';
import { jsonConfig } from './path-of-configuration'
...

	render(){
		return (<DittoFilter ditoConfig={jsonConfig}/>)
	}

Ejemplo de configuración

{
"restConnector":{
	"host":"localhost:9290/host",
	"method":"GET",
	"url":"/some/url",
	"attrList":"invoices",
	"searchOpen":true
},
"pagination":{
	"total":"total_elements"
},
"sidePadding":50,
"inputList":[
	{
		"type":"date-simple",
		"keyElement":"creationDate",
		"keyOutput":"creation_date",
		"label":"Received Date From",
		"format":"YYYY-MM-DD",
		"required":true
	},
	{
		"type":"select-by-rest",
		"host":"localhost:9290/host",
		"keyElement":"statusType",
		"keyOutput":"status_type",
		"label":"Status Type",
		"placeholder":"Select Status Type",
		"flat":true,
		"url":"/some/url/catalog"
	},
	{
		"type":"text",
		"keyElement":"purchaseOrder",
		"keyOutput":"purchase_order",
		"label":"Purchase Order",
		"placeholder":"insert purchase order",
		"priority":true
	}
],
"buttonsList":[
	{
		"type":"button",
		"mode":"clear",
		"keyElement":"reset",
		"label":"Reset"
	},
	{
		"type":"button",
		"mode":"submit",
		"keyElement":"search",
		"label":"Filter"
	}
]
}

Este objeto de configuración esta compuesto por:

• restConnector
• pagination
• multipleChoice
• inputList
• buttonsList
• actions
• onlyTable
• sidePadding
• onlyFilters
• inputOrder
• buttonsOrder
• actionsOrder

Descarga y uso local

$ git [email protected]:despegar/cfa-ditto.git
$ cd cfa-ditto

Para correr la aplicación de forma local es necesario tener instalado.

• nodejs
• npm

Clonar el proyecto.

$ git [email protected]:despegar/cfa-ditto.git
$ cd cfa-ditto

descargar e instalar dependencias

$ npm install

Correr la aplicación

$ npm start

esto levanta un server de react app con un elemento "ditto-filter" inyectado con una config de ejemplo, para poder probar y desarrollar nuevas funcionalidades

Stack

• Ant Design
• React

Para una ejemplo interactiva vistar: https://ditto-app.netlify.com/

API

restConnector (Object)

Se establecen las configuraciones para la conexión al endpoint de donde se enviaran los datos de filtros y se obtendrán los datos para ser dibujados. Todos los valores no vacíos de los filtros, al momentos del submit, se enviaran mediante query params o query string según como este configurado (GET) o mediante un body (POST)

| Property | Description | Type | Default |--|--|--|--| | host | host | String | - |method|Tipo de llamada rest | String | GET |url| Restante del endpoint. Si se necesita enviar algún valor mediante queryString en la url debe incluir la sintaxis ":keyElement". Los valores de filtros restantes se enviaran mediante query params (GET) o en un body (POST) | String | - |attrList| atributo del objeto de respuesta en donde se encuentra la lista de items, que se dibujara en la tabla de resultados | String |content |headers| agregar headers al request realizado por ditto para la busqueda de resutlados. Ej {'x-version-override':'pigeon-beta'} |Object|- |searchOpen| flag que indica si al iniciar al dibujar la pagina, se realiza una búsqueda inicial | boolean | true

pagination (Object)

En caso de que que el servicio de consulta acepte paginado, acá se configuran atributos para tomar valores de total de elementos, desplazamientos y con estos datos armar la barra de paginado

| Property | Description | Type | Default |--|--|--|--| | total | property de objeto de respuesta en donde se encuentra el total de elementos de la consulta. Con este valor automaticamente se dibujara las cantidad de paginas en base al limite seleccionado en este mismo elemento | String | -

Si se utiliza paginado, a la query realizada se enviara mediante el parámetro "offset" el numero de la pagina solicitada, y en "limit" la cantidad de registros pedidos por pagina.

Si no se configura pagination o se lo seta con valor nulo, se utilizara el paginado default de AntDesign, el cual espera la totalidad de registros en la respuesta, y hace un paginado en memoria.

sidePadding (Integer)

valor numérico para establecer un margen a los costados de la sección filtro

multipleChoice (Object)

Opcion configurable, en el caso que se necesiten realizar acciones en base a multiple registros seleccionados.

| Property | Description | Type | Default |--|--|--|--| | objectId | property de objeto de respuesta que identifica a un registro. Permite filtrar internamente para tener los multiples registros seleccionados | String | - |validate| funcion que permite hacer validaciones sobre que casos, puede seleccionarse o no un registro. Ej: token no nulo| function(record):: Boolean| true |showSelectionButtons|Mostrar acciones de 'Selleccionar Todo'/'Deseleccionar todo' sobre la grilla actual de resultados | Boolean | false

En caso de que se utilice seleccion multiple, todos los componentes customs recibiran en la prop selectedItems, la lista de registros seleccionados, para poder operar con ellos libremente y realizar las acciones que se necesiten

Si se quiere fijar alguna columna hacia la derecha y se encuentra activo el multipleChoice, esta se debe fijar también ya que está posterior al listado de columnas de inputList. Si no se fija esta columna, se rompe el display.

onlyTable (boolean)

flag que establece si solo se requiere el dibujado de la tabla, y omitir la sección de filtros y botones de clear o submit.

onlyFilters (boolean)

flag que establece si solo se requiere un form de filtros, omitiendo el hecho de hacer la query y el dibujado de la tabla de resultados.

inputList (List[Object])

Lista de objeto de configuración en donde se establecen los filtros que se dibujaran en pantalla y columnas que se mostraran como resultado. Por defecto, todo filtro que se dibuja por pantalla, es una columna que se muestra como resultado (puede ser configurado).

Configuraciones generales:

| Property | Description | Type | Default |--|--|--|--| |type| Tipo de filtro o columna que sera dibujado por pantalla. Valores: text / numeric / select / select-by-rest / date-range / date-simple /date-period / checkbox / column / custom-column/file-text | String | - | keyElement | Valor que sera utilizado como identificador, en aquellos elementos que pueden referenciar a otros. A su vez, con esta key se realizaran las querys con el valor del filtro correspondiente por queryString/queryParam/body segun corresponda. Por defecto tambien con esta property se buscara en el objeto de respuesta, para dibujar el resultado en la tabla| String| - | keyOutput| En caso de que en el objeto de respuesta de la query, el contenido de la property a dibujar sea diferente al keyElement, en este atributo podrá redefinir dicha key | String | - |label | Texto que saldrá como encabezado del filtro o columna | String | - |placeholder| texto de placeholder que se mostrara en dicho input. (No aplica para elementos de tipo columna).| String | - |span | tamaño que tendrá el elemento de filtro dentro de la pantalla.(No aplica para elementos de tipo columna).| Integer (1-24) | 6 |required|flag que indica si este elemento es necesario que sea completado para poder hacer el submit y llamar a la query | boolean | false| |hide| Si el resultado de un filtro, no quiere mostrarse en la tabla de respuesta, debe marcar este flag como true | boolean | false |priority| este flag indica si dicho elemento tiente prioridad sobre los elementos requeridos. Si este valor esta activo y el filtro tiene algún valor, omitirá la validación de los inputs requerido e igualmente hará la llamada a la query. | boolean | false |disableOnPriority| para los elementos que sean requeridos, este flag indicara si ante un override en las validaciones por un elemento con prioridad, si este valor de filtro se ignorar y/o deshabilitar | boolean | false |outputType| permite definir el tipo de dato de salida. Por ahora solo permite diferenciar el tipo de dato primtivo del input correspondiente, o si se desea utilizar, el tipo lista (List) | String | - |split| Si se utiliza el tipo de dato lista (outputType), se puede establecer en este atributo una regex, por el cual se hara el split de la cadena de datos y armar la lista de salida | String / Regexp | ',' |renderFunction| funcion que permite modificar el texto que se mostrara en la tabla | function | - |onDemandProps| configuracion que permite añadir props no tipadas por ditto, directamente sobre el componente de Ant. Sobreescribe cualquier props ya configurada previamente | Object {key: value} | - |fixed| fija la columna al hacer scroll horizontal. La columna debe respetar el orden en el que se vaya a mostrar. Por ejemplo, si se fija una columna a la izquierda, esta debe ser la primera en el listado de inputList o siguiente de una ya fijada. Si se quiere fijar una columna a la derecha, esta debe ser la última del listado de inputList o anterior a una fijada. Si se quiere fijar una columna hacia la derecha y se utiliza el multipleChoice, deben fijarlo también para que no rompa el display | String ("left", "right") | -

Configuraciones según tipo de filtro:

ademas de las configuraciones generales, según el tipo de filtro que se selecciona, tendrá la posibilidad de otras configuraciones adicionales que ira en este mismo de objeto.

Combo Select Simple:

Combo en donde se podrán configurar valores establecidos

| Property | Description | Type | Default |--|--|--|--| |options| Atributo donde se indica los valores que se mostraran en el combo mediante un una lista de tipo {val: valorAenviar, descr: valor a mostrar} | List<{val:, descr:}> | - |multiple| posibilidad de seleccionar multiples opciones del combo.|boolean|false |maxTagCount| cantidad de descripciones seleccionadas que se muestran en el combto| integer|1

Combo Select by Rest:

Combo que se llenara según el resultado de una llamada a un endpoint configurado.

| Property | Description | Type | Default |--|--|--|--| |host| Host del endpoint | String | - |url| Restante de la url | String | - |flat| Si la respuesta a dicho servicio es una simple lista de valores, este flag debe estar activo, para establecer como value y description dicho valor| boolean | false |valKey| Si la respuesta es un objeto mas complejo, en esta property se deberá indicar la key del objeto de donde tomar el "value" del combo | String | "val" |descrKey| Si la respuesta es un objeto mas complejo, en esta property se deberá indicar la key del objeto de donde tomar la Descripción del combo | String | "descr" |referenceKey| Posibilidad de añadir un parámetro al servicio para obtener los datos del combo, que sea un valor de algún otro filtro. debe indicarse el keyElement de dicho input. Al cambiar el valor del componente referenciado se volverá a llamar al endpoint con el nuevo valor.|String | - |multiple| posibilidad de seleccionar multiples opciones del combo.|boolean|false |maxTagCount| cantidad de descripciones seleccionadas que se muestran en el combto| integer|1

Input Date Simple: Tipo de filtro fecha, en donde se mostrar un calendario para elegir una fecha en particular

| Property | Description | Type | Default |--|--|--|--| |format| formato de fecha que se mostrara tanto en el filtro, como formato que se enviara en los parámetros de la query. Ver formatos | String | DD-MM-YYYY |formatOutput| en caso de que el formato de salida difiera con lo que se muestra en pantalla, en este campo se puede hacer esa redefinición| String | - |disableDefault| Por defecto el input se seteara con el dia actual. Se puede desactivar con esta prop y dejar vacio el filtro| Boolean | false

Los restantes tipo de input dates, date-period (selección de fecha por mes), y date-range (selección de un intervalo de fecha en un mismo calendar) utilizan estas mismas configuraciones.

file-text input: Tipo de filtro, que permite seleccionar un archivo texto plano del equipo, parsearlo, y los valores obtenidos enviarlos en el request. Ej: un csv con una lista de ids.

| Property | Description | Type | Default |--|--|--|--| |extension| configurar extension de archivo valido para la carga| String | -

buttonsList (List[Object])

Lista de objetos de configuración en donde se establecen los botones que aparecerán en la parte inferior de la sección de filtros. Ya se encuentran dos botones preestablecidos, con la posibilidad de agregar los propios.

| Property | Description | Type | Default |--|--|--|--| |type| Tipo de elemento, en esta sección por el momento solo existe el tipo button| String | - |mode| Modalidad del botón: clear / submit / custom. clear: es un modo por defecto, que limpia todos los valores de los filtros automaticamente. submit: es el boton por defecto que corre las validaciones configuradas y realiza la llamada al endpoint establecido en restConnector| String | - |keyElement| Identificador del botón | String | - |label| Texto que se mostrara en el botón| String | - |cleanSearch| Para el boton de reset/clear, se podra configurar si se desea volver a ejecutar la busqueda con los filtros vacios| Boolean | false

actions (List[Object])
Lista de objetos de configuración en donde se establecen las acciones que se pueden realizar sobre un elemento seleccionado de la tabla de respuesta en particular, o el conjunto de respuesta. Puede ser acciones predefinidas, como mostrar el nombre de algun atributo, descarga de un archivo, o acciones custom.

Configuraciones generales:

| Property | Description | Type | Default |--|--|--|--| |type| Tipo de acción a realizar - name / download / custom-action| String|- |keyElement | Identificador de la acción | String | - |referenceId| Property de referencia al objeto de respuesta, para utilizar dicho dato en la acción determinada. Generalmente es algún valor que se encuentra en el keyElement o keyOutput en algún elemento de inputList

Detalle y configuraciones adicionales según tipo de acción:

ademas de las configuraciones generales, según el tipo de acción , existen otras configuraciones adicionales que ira en este mismo de objeto.

Mostrar Nombre (name): Con este tipo de acción, se mostrara en el encabezado algún atributo en particular de la respuesta, para identificar el registro seleccionado

Descarga de Archivo (download): Permite la descarga de un archivo indicando la url del servicio al cual se realizara la llamada para obtener el documento, configurar extensiones y nombre de archivo. Por default, se descargara el archivo con el valor que venga en el header del request de "content-disposition / filename=".

| Property | Description | Type | Default |--|--|--|--| |text| Texto que aparecerá en el botón de descarga| String | - |icon| Icono que se dibujara en el botón de descarga. Ver iconos | String | download |referenceId| Property del objeto de respuesta de donde obtendra el valor, que se usara en el servicio configurado para obtener el documento| String | - |url| Url del servicio. Utilizar la sintaxis "!val" dentro de la url para indicar en donde va el valor refernciado mediante el referenceId. Por Ejemplo - url:"documents/file/!val/data"| String| - |fileNameReference| En caso de que se quiera usar algún valor del objeto de respuesta como nombre del archivo, en esta property se debe indicar dicho atributo. Si esto se realiza, es requerido indicar la extension del archivo|String| - |extension| Extension del archivo| String | - |fileNamePrefix| Se puede establecer un prefijo en el nombre final del archivo|String|- |fileNameSuffix| Se puede establecer un sufijo en el nombre final del archivo| String | -

Componentes Customs

Ditto da la posibilidad de poder utilizar componentes realizados por el usuario, para contemplar casos de usos, que no podrían resolverse con las acciones que Ditto provee y se dibujaran en el lugar del elemento que se haya indicado que es de tipo custom, mediante el keyElement.

Ejemplo de implementación

Objeto de configuracion
{
	...
	inputList:[
		...
		{
			type:  "custom-column",
			keyElement:  "errorMsg",
			label:  "Message Error"
		}
		...
	],
	...
}

El componente custom que se quiera dibujar, a nivel sintaxis, debe estar indicado como un hijo (children) del componente general DittoFilter e indicar una prop componentId el valor del keyElement que se haya establecido en la configuración.

import { DittoFilter } from 'cfa-ditto';
import  ComponenteCustom  from '/path-of-component';
import { jsonConfig } from './path-of-configuration-with-custom-component'
...

	render(){
		return (<DittoFilter ditoConfig={jsonConfig}>
					<ComponenteCustom componentId="errorMsg"/>
				</DittoFilter>
		)
	}

Todos los Componentes Custom recibirán mediante las siguientes props los datos de filtros y registros para que el usuario pueda realizar el código que necesite:

• record: en esta prop se encontrara el registro seleccionado de la tabla de respuesta
• refetch: en esta prop se recibe la función para volver a ejecutar la ultima query realizada, en caso de que se necesite tras una acción custom, refrescar la tabla de resultados
• filtersValue: en esta prop se recibe un objeto con todos los keyElements de los filtros y su valor actual correspondiente
• responseData: en esta props se recibe la lista de elementos dibujada en la tabla de respuesta actualmente
• selectedItems: en caso de utilizar seleccion multiple, aqui se encuentran la lista de registros seleccionados

default (Object) La api de Ditto provee la posibilidad de establecer un template default, los cuales rigen las mismas configuraciones antes descriptas. Es de utilidad si se tienen distintos archivos de configuraciones, son similares elementos. Los elementos comunes se pueden abstraer a un único objeto de configuración, definirlo en el "default", y redefinir cosas en el main.

	export cosnt defaultConfig= {
		...
		restConnector:{
			host: "http://somehost.com"
			url: "/defualt/endpoint"
			method: "GET"
		},
		sidePadding: 50
		...
	}

import { defaultConfig } from  ".some/path/configs";
...
	cosnt overrideConfig= {
		defualt: defaultConfig
		...
		restConnector:{
			url: "/override/endpoint"
			method: "POST"
		}
		sidePadding:200
		...
	}
...

Configuración resultante :

...
	mergedConfig = {
		...
		restConnector:{
			host: "http://somehost.com"
			url: "/override/endpoint"
			method: "POST"
		}
		sidePadding:200
		...
	}
...

inputOrder / buttonsOrder / actionsOrder (List (String - keyElement)) Por default, los elementos se dibujan en pantalla, en base al orden en que estén dispuestos en la configuración principal. Si se llega a utilizar un template default, al momento de hacer el "merge" entre ambos objetos, es posible que el orden final no sea el esperado. Para este caso, se puede definir una lista de keyElement del cual se tomara como referencia para dibujar en pantalla según el orden correspondiente en el atributo especificado. inputOrder -> filtros y columnas, buttonsOrder -> botones, actionsOrder -> acciones