awe-103 Criterios, grids y gráficos

Este tutorial se centra en los elementos de pantalla orientados a datos más habituales de AWE: criterios para la entrada, grids para resultados tabulares y gráficos para resúmenes visuales. Considere esta página como el camino práctico. Cuando necesite todas las variantes o todos los atributos, acuda a la referencia de la API en lugar de tratar el tutorial como un catálogo de componentes.

Ruta rápida

1. Empiece con un pequeño conjunto de criterios.
2. Vincule esos criterios a un grid respaldado por una query.
3. Añada validación y componentes de selección solo donde mejoren el flujo.
4. Introduzca los gráficos cuando el camino de los datos ya esté claro.

Antes de empezar

Ya debería saber cómo crear la estructura de una pantalla a partir de awe-102.

El camino habitual es este:

criteria -> query or enumerated -> grid or chart -> actions/dependencies

Si tiene dudas sobre las fuentes de datos, mantenga abierto awe-104 mientras lee esta página.

Paso 1: Empiece con los criterios

Los criterios recogen la entrada del usuario, filtran datos y guardan valores que las acciones posteriores envían al servidor.

Utilice primero el conjunto de criterios más pequeño que resulte útil. Una pantalla con tres criterios bien elegidos suele ser más fácil de entender que una con todos los tipos de campo posibles.

Forma del XML de un criterio

<criteria ... />

Forma completa de ejemplo:

<screen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/screen.xsd"
        template="window"
        label="SCREEN_TITLE_USR"
        help="HELP_SCREEN_TITLE_USR"
        keep-criteria="true">
  <tag>
    <criteria id="[identifier]" component="[component]" label="[label]" placeholder="[placeholder]" style="[classes]"
              initial-load="[initial-load]" server-action="[server-action]" target-action="[target-action]"
              variable="[variable]" value="[value]" session="[session]" property="[property]"
              validation="[validation]" readonly="[read-only]" size="[size]" unit="[unit]" icon="[icon]"
              printable="[printable]" help="[help]" help-image="[help-image]"
              optional="[optional]" area-rows="[area-rows]" number-format="[number-format]" capitalize="[capitalize]"
              strict="[strict]" checked="[checked]" group="[group]" show-slider="[slider]" destination="[destination]">
      <dependency/>
    </criteria>
  </tag>
</screen>

Solo dos atributos son siempre fundamentales:

• id: referencia interna
• component: tipo de criterio

Para la referencia completa de atributos, utilice:

• API de criteria
• API de dependencies

El patrón base: criterios de texto

Los criterios de texto son la forma más sencilla de aprender el modelo.

<criteria id="TextCrt" component="text" label="Text" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Esto le da un campo de texto cuyo valor enviado está disponible con el identificador del criterio, salvo que lo redirija con variable.

Primeros refinamientos útiles:

Valor por defecto

<criteria id="TextCrt" component="text" label="Text" value="Test text" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Placeholder

<criteria id="TextCrt" component="text" label="Text" placeholder="Introduce a text" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Valor inicial desde una query

Utilícelo solo cuando la carga inicial de la pantalla dependa realmente de datos del servidor.

Pantalla

<criteria id="TextCrt" component="text" label="Text" initial-load="value" target-action="GetOpe" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Query

<query id="GetOpe">
  <table id="ope" alias="ope" />
  <field id="openam" alias="label" />
  <field id="openam" alias="value" />
  <where>
    <and>
      <filter left-field="l1_nom" condition="eq" right-variable="Usr" ignorecase="true" />
    </and>
  </where>
  <variable id="Usr" type="STRING" value="mgr" />
</query>

Valor procedente de una pantalla anterior

Al navegar entre pantallas, utilice variable para recuperar un valor que ya está presente en el contexto anterior.

Validación

Utilice la validación para proteger el camino feliz en lugar de enviar al servidor errores evidentes.

Ejemplo de campo obligatorio:

<criteria id="TextCrt" component="text" label="Text" validation="required" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

<button button-type="submit" label="BUTTON_SEARCH" icon="search" id="ButSch" help="HELP_SEARCH_BUTTON">
  <button-action type="validate" />
</button>

Ejemplo de longitud mínima:

<criteria id="TextCrt" component="text" label="Text" validation="{minlength:10}" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Para el conjunto completo de validaciones, utilice la API de criteria.

Solo lectura, tamaño, unidad e icono

<criteria id="TextCrt" component="text" label="Text" readonly="true" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

<criteria id="TextCrtSM" component="text" label="Text" size="sm" value="size sm" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />
<criteria id="TextCrtMD" component="text" label="Text" size="md" value="size md" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />
<criteria id="TextCrtLG" component="text" label="Text" size="lg" value="size lg" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

<criteria id="TextCrt" component="text" label="Text" unit="EUR" value="10.000" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

<criteria id="TextCrtSM" component="text" label="Text" icon="hand-o-right" value="Test text" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Otras familias habituales de criterios

Utilice las familias siguientes como guía de decisión. Acuda a la documentación de la API cuando necesite atributos de casos límite.

Familia de entrada de texto

Contraseña:

<criteria id="Identifier" label="Password" component="password" variable="password" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Área de texto:

<criteria id="Identifier" label="Textarea" component="textarea" variable="Textarea" style="col-xs-12 col-sm-6 col-lg-6" />

Valor oculto:

<criteria id="Identifier" variable="NumberHidden" component="hidden" value="4" />

Texto de solo lectura para visualización:

<criteria label="Text" id="TxtViw" variable="ButVal" component="text-view" style="col-xs-6 col-sm-3 col-lg-2" icon="download" />

Referencias relacionadas:

• API de criteria
• Botones en awe-102

Entradas numéricas y de fecha

Numérico:

<criteria id="Identifier" label="Numeric" component="numeric" show-slider="true" number-format="{min: 0, max: 100, step: 1, precision: 2, pSign:'s', aPad:true}" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Fecha:

<criteria label="Date" id="Cal" variable="Cal" component="date" style="col-xs-6 col-sm-3 col-lg-2" validation="{le: {criterion:'CalReq', type: 'date'}}" show-weekends="false" show-future-dates="false" />

Hora:

<criteria label="Time" id="Tim" variable="Tim" component="time" style="col-xs-6 col-sm-3 col-lg-2" />

Calendario filtrado:

<criteria label="PARAMETER_FILTERED_DATE" id="FilCal" variable="FilCal" component="filtered-calendar" initial-load="query" target-action="FilCalDat" style="col-xs-6 col-sm-3 col-lg-2" validation="{le: {criterion:'FilCalReq', type: 'date'}}" />

Entradas de selección

Select:

<criteria id="TextCrtSM" component="select" label="Select" initial-load="enum" target-action="demoEnum" optional="true" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Select múltiple:

<criteria id="TextCrtSM" component="select-multiple" label="Select" initial-load="enum" target-action="demoEnum" optional="true" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Suggest:

<criteria id="TextCrtSM" component="suggest" label="Select" target-action="getUsers" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Suggest múltiple:

<criteria id="TextCrtSM" component="suggest-multiple" label="Select" target-action="getUsers" style="col-xs-12 col-sm-6 col-md-3 col-lg-2" />

Grupo de casillas de verificación:

<criteria label="Checkbox 1" id="ChkBoxVa1" group="ChkBoxVa" variable="ChkBoxVa1" component="checkbox" style="col-xs-6 col-sm-4 col-lg-2 no-label"/>
<criteria label="Checkbox 2" id="ChkBoxVa2" group="ChkBoxVa" variable="ChkBoxVa2" component="checkbox" style="col-xs-6 col-sm-4 col-lg-2 no-label"/>

Grupo de botones de opción:

<criteria label="Radio 1" id="RadBox1" group="RadBoxGrp1" variable="RadBoxGrp1" component="radio" value="Radio1" style="col-xs-6 col-sm-4 col-lg-2 no-label" validation="required" />
<criteria label="Radio 2" id="RadBox2" group="RadBoxGrp1" variable="RadBoxGrp1" component="radio" value="Radio2" style="col-xs-6 col-sm-4 col-lg-2 no-label" readonly="true" />

Casilla de verificación con aspecto de botón:

<criteria label="Checkbox 1" id="ChkBoxVa21" group="ChkBoxVa2" variable="ChkBoxVa21" component="button-checkbox" style="col-xs-2"/>

Botón de opción con aspecto de botón:

<criteria label="Radio 1" id="RadBox21" group="RadBoxGrp2" variable="RadBoxGrp2" component="button-radio" value="Radio1" style="col-xs-2" validation="required" />

Criterios de propósito especial

Selector de color:

<criteria label="Color" id="Col" variable="Col" component="color" style="col-xs-6 col-sm-3 col-lg-2" />

Carga de archivos:

<criteria label="File" id="Upl" variable="Upl" component="uploader" style="col-xs-12 col-sm-6 col-lg-4" />

Son útiles, pero rara vez lo primero que se añade a una pantalla. Es preferible introducirlos cuando el formulario básico y el flujo de datos ya funcionen.

Paso 2: Vincule la pantalla a un grid

Los grids son el componente principal de AWE para las listas de resultados. Normalmente se alimentan de una query y se controlan mediante criterios y acciones.

<grid id="[grid-identifier]" ...>
  <column ...></column>
  <group-header ...>
    <column ...></column>
  </group-header>
  <button ...> ... </button>
  <context-button ...> ... </context-button>
</grid>

Estructura básica:

<grid id="[grid-id]" style="[grid-style]" multiselect="[grid-is-multiselect]" checkbox-multiselect="[checkbox-multiselectable]" editable="[grid-is-editable]" send-operations="[grid-is-multioperation]" initial-load="[initial-load]" server-action="[server-action]" target-action="[target-action]" max="[elements-per-page]" pagination-disabled="[pagination-disabled]">
  ...
</grid>

<column label="[column-label]" name="[column-name]" sort-field="[sort-field]" align="[text-align]" charlength="[column-width-chars]" component="[column-component]" >
  <dependency ...> ... </dependency>
</column>

Los atributos iniciales más importantes son:

• id en el grid
• name en la columna
• server-action y target-action cuando el grid carga datos del servidor

Consulte la referencia completa en la API de grids.

Grid sencillo

<grid id="GrdSta" style="expand" initial-load="query" server-action="data" target-action="QryUniTstId" max="30">
  <column label="PARAMETER_TEXT" name="Als" sort-field="Als" align="left" charlength="20" style="separator" />
  <column label="PARAMETER_TEXT" name="Des" sort-field="Des" align="left" charlength="40" />
  <column label="PARAMETER_TEXT" name="Prg" sort-field="Prg" align="center" charlength="40" component="progress" value="40" server-action="data" target-action="QryChkPrg" printable="false" />
  <column label="PARAMETER_TEXT" name="DwnFil" sort-field="Des" align="left" charlength="50" component="text-view" icon="download" />
  <column label="PARAMETER_TEXT" name="TxtViw" sort-field="Des" align="right" charlength="10" component="text-view" printable="false"/>
  <column label="PARAMETER_TEXT" name="TxtSty" sort-field="Des" align="right" charlength="10" printable="false"/>
</grid>

Esta es la forma adecuada de un primer grid para la mayoría de los tutoriales: respaldado por una query, ordenable, paginado y de solo lectura.

Agrupación de cabeceras

Utilice group-header cuando las columnas se lean mejor como un bloque visual.

<group-header name="GrpHeaCol" label="PARAMETER_TEXT">
  <column label="PARAMETER_TEXT" name="Des" sort-field="Des" align="left" charlength="40" />
  <column label="PARAMETER_TEXT" name="Prg" sort-field="Prg" align="center" charlength="40" component="progress" value="40" server-action="data" target-action="QryChkPrg" printable="false" />
</group-header>

Grids multiselección, editables y multioperación

Utilícelos solo cuando el usuario los necesite de verdad:

• multiselect="true" cuando el usuario actúa sobre varias filas a la vez
• editable="true" cuando la edición en línea es la mejor experiencia de usuario
• send-operations="true" cuando un solo guardado debe agrupar inserciones, actualizaciones y borrados

Ejemplos:

<grid ... multiselect="true" ...>
  ...
</grid>

<grid ... editable="true" ...>
  <button label="BUTTON_NEW" icon="plus-circle" id="ButGrdEdiAdd">
    <button-action type="add-row" target="GrdEdi" silent="true" />
  </button>
  <button label="BUTTON_DELETE" icon="trash" id="ButGrdEdiDel">
    <button-action type="delete-row" target="GrdEdi" silent="true" />
    <dependency source-type="none" target-type="enable" initial="true">
      <dependency-element id="GrdEdi" attribute="selectedRows" condition="eq" value="1" />
    </dependency>
  </button>
</grid>

<grid ... editable="true" send-operations="true" ...>
  ...
</grid>

Importante: si las ediciones del grid deben persistir, sigue siendo necesaria una acción de servidor que llame a un maintain.

Grids en árbol

Los grids en árbol sirven para datos jerárquicos, no solo para dar variedad visual.

<grid ... treegrid="true" expand-column="TreGrd_Nam" tree-id="TreGrd_id" tree-parent="TreGrd_parent" initial-level="3" ...>
  <column label="PARAMETER_NAME" name="TreGrd_Nam" sort-field="TreGrd_Nam" align="left" sortable="false" charlength="40" />
</grid>

Si además hay que editar la jerarquía, combine treegrid="true" con editable="true".

Paso 3: Añada gráficos cuando el camino de los datos sea estable

Los gráficos son útiles cuando el usuario necesita tendencias, comparaciones o resúmenes. No sustituyen al aprendizaje previo del flujo de queries y grids.

<chart id="[Chart Id]" label="[Chart title]" subtitle="[Chart subtitle]" type="[Type chart]" initial-load="[Initial load]" target-action="[Action]">
  <chart-legend layout="[Layout]" align="[Align]" verticalAlign="[Vertical align]" />
  <x-axis label="[Label X-Axis]" type="[Type axis]"/>
  <y-axis label="[Label Y-Axis]"/>
  <chart-tooltip suffix="[Suffix value]" number-decimals="[Decimal numbers]"/>
  <chart-serie id="[Serie ID]" x-value="[X-Values]" y-value="[Y-value]" label="[Serie label]" />
</chart>

Ejemplo:

<chart id="ChrLinTst" label="SCREEN_TEXT_CHART_TITLE_1" subtitle="Subtitulo grafico 1" type="mixed" initial-load="query" target-action="TstChrTwoSrc" zoom-type="xAxis" max="30" help-image="HELP_CHART_IMAGE_1">
  <chart-legend label="Leyenda" />
  <x-axis label="Fechas" type="datetime" />
  <y-axis label="Temperaturas (ºC)" formatter-function="formatCurrencyMagnitude"/>
  <y-axis opposite="true" label="Lluvias (mm)" />
  <chart-tooltip crosshairs="xAxis" suffix=" ºC" number-decimals="3" shared="true"/>
  <chart-serie id="serie-1" y-axis="0" x-value="dates" y-value="serie1" type="column" label="Serie 1" color="#A8E0A6" />
  <chart-serie id="serie-2" y-axis="1" x-value="dates" y-value="serie2" type="spline" label="Serie 2" />
  <context-button id="CtxLinTstRef" label="BUTTON_RELOAD" icon="refresh">
    <button-action type="server" server-action="data" target-action="TstChrTwoSrc" target="ChrLinTst" />
  </context-button>
</chart>

Para el modelo completo de gráficos, utilice la API de chart.

Qué hacer a continuación

• Vaya a awe-104 cuando necesite definir las fuentes de datos subyacentes.
• Vaya a awe-106 cuando estos componentes deban reaccionar a las acciones del usuario o entre sí.
• Utilice la documentación de la API para consultar todas las variantes de los componentes en lugar de sobrecargar la primera implementación.