Version: Next (5.0)

awe-102 Diseño de ventanas

Este tutorial continúa desde awe-101 y muestra el primer camino práctico para construir una pantalla en AWE: crear el XML de la pantalla, añadir las etiquetas que necesita, situarla en el menú y dar forma al diseño con los principales componentes contenedor.

Ruta rápida

Cree un archivo XML de pantalla en application/<your-acronym>/screen/.
Defina la estructura básica de <screen> y elija una plantilla.
Añada los locales que usan el título y las etiquetas de la pantalla.
Registre la pantalla en public.xml o private.xml.
Utilice ventanas, etiquetas de diseño, botones y diálogos para organizar la página.

Antes de empezar

Debería sentirse cómodo con la estructura de la aplicación generada que se explica en awe-101.

Tenga presentes estas carpetas:

src/main/resources/application/<your-acronym>/
├── global/
├── locale/
├── menu/
├── profile/
└── screen/

La pantalla en sí vive en screen/, pero normalmente depende de locale/ para los textos y de menu/ para que los usuarios puedan llegar a ella.

Paso 1: Cree el archivo de la pantalla

Lo más seguro y rápido suele ser copiar una pantalla parecida y simplificarla. Si empieza desde cero, cree un nuevo archivo XML dentro de screen/ y comience con el esqueleto válido más pequeño.

<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 source="buttons">
    ...
  </tag>
  <tag source="center">
    ...
  </tag>
  <tag source="hidden">
    ...
  </tag>
</screen>

Lo que importa primero:

template elige la estructura general de la pantalla.
label apunta al locale que se usa como título de la pantalla.
help apunta, de forma opcional, al texto de ayuda de la pantalla.
tag source="..." inserta contenido en los puntos de entrada de la plantilla.

Utilice la referencia de la API cuando necesite la lista completa de atributos en lugar de memorizarla:

Paso 2: Añada los textos de la pantalla en los archivos de locale

Toda etiqueta visible debe proceder de los archivos de locale de locale/Locale-<LANG>.xml.

<locales xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/locale.xsd">
  ...
  <locale name="LOCALE_IDENTIFIER" value="Locale text"/>
  ...
</locales>

Adiciones habituales para una pantalla nueva:

un locale para el título de la pantalla
un locale para el texto de ayuda, si lo utiliza
un locale para cada botón o etiqueta de sección visible que introduzca

Si su flujo de trabajo aún espera que los locales se mantengan ordenados alfabéticamente, conserve esa convención en todos los idiomas.

Si más adelante quiere ayuda de herramientas para el mantenimiento de locales, consulte awe-105.

Los usuarios no llegarán a la pantalla hasta que aparezca en menu/public.xml o en menu/private.xml.

<menu screen="home_horizontal"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:noNamespaceSchemaLocation="https://aweframework.gitlab.io/awe/docs/schemas/menu.xsd"
      context="screen/private/home"
      default-action="screen">
  <option name="tools" label="MENU_TOOLS" icon="wrench">
    <option name="my-screen" label="MENU_MY_SCREEN" screen="my-screen" icon="desktop" />
  </option>
</menu>

Tenga clara esta correspondencia:

name: identificador único de la opción de menú
label: locale que se muestra al usuario
screen: nombre del archivo de la pantalla sin .xml

Las opciones de primer nivel aparecen en la barra de herramientas principal. Las opciones anidadas aparecen en submenús.

Paso 4: Elija las áreas de pantalla adecuadas

La plantilla determina qué áreas source están disponibles.

Plantilla	Uso principal	Sources disponibles
`full`	Diseños libres	`center`, `modal`, `hidden`
`window`	La mayoría de las pantallas estándar de una aplicación	`center`, `buttons`, `modal`, `hidden`
`document`	Pantallas que muestran un documento, como el manual de la aplicación	`center`, `buttons`, `modal`, `hidden`

Consulte la API de plantillas para ver el detalle de cada plantilla y cómo añadir las suyas.

Regla práctica:

Empiece con window, salvo que necesite claramente una composición de página a medida.
Utilice buttons para las acciones de toda la pantalla.
Utilice center para el contenido principal.
Utilice modal para los diálogos.
Utilice hidden para los mensajes y los componentes auxiliares internos.

Paso 5: Construya el diseño con los componentes básicos

Añada estructura HTML sencilla con `tag`

tag puede renderizar elementos HTML estándar si se establece su atributo type.

<tag type="div" style="my-class" id="test"></tag>

Esto se convierte en:

<div class="my-class" id="test"></div>

Consulte la API de tags cuando necesite todas las opciones.

Agrupe contenido relacionado con `window`

window es el contenedor visual más habitual en las pantallas de AWE.

<window label="SCREEN_TEXT_CRITERIA" icon="filter">
  <tag type="div" style="panel-body">...</tag>
  <tag type="div" style="panel-footer">
    <tag type="div" style="pull-right">...</tag>
  </tag>
</window>

Utilícela para separar áreas lógicas como filtros, datos o paneles de resumen.

Si la ventana contiene un grid o un gráfico, normalmente puede colocar ese componente directamente dentro de la ventana:

<window label="SCREEN_TEXT_DATA" icon="list" maximize="true">
  <grid id="myGrid" ...>
    ...
  </grid>
</window>

Controle la expansión y las áreas estáticas

Para que un hijo ocupe el espacio disponible, marque el padre como expandible y el hijo como expand.

<tag source="center" type="div" expandible="vertical">
  <window label="SCREEN_TEXT_CRITERIA">
    ...
  </window>
  <window label="SCREEN_TEXT_DATA" style="expand">
    ...
  </window>
</tag>

Este patrón es habitual cuando quiere un área de filtros fija encima de un área de datos que crece con la pantalla.

Consulte la API de layout para ver todas las combinaciones de diseño.

Paso 6: Añada los principales contenedores interactivos

Botones

Los botones son el punto de entrada habitual de las acciones de la pantalla.

<button label="BUTTON_NEW" icon="plus" id="ButNew">
  <button-action type="screen" target="newWindow" />
</button>

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

El segundo patrón es el flujo de búsqueda habitual: validar los criterios y después recargar el grid de destino.

Más información en la API de button.

Pestañas

Utilice pestañas cuando una pantalla contenga secciones claramente separadas.

<tab id="tabId" initial-load="[initial-load]" target-action="[enumerated-query-identifier]">
  <tabcontainer id="idTabcontainer1">
    ...
  </tabcontainer>
  <tabcontainer id="idTabcontainerN">
    ...
  </tabcontainer>
</tab>

Las pestañas suelen cargar sus etiquetas y valores desde un enumerado o desde una query. Para ver todas las variantes, utilice la API de tab y tabcontainer.

Asistentes

Utilice asistentes (wizards) cuando el usuario deba avanzar a través de una secuencia de pasos.

<wizard id="idWizard" initial-load="[initial-load]" target-action="[enumerated-query-identifier]" label="LOCALE">
  <wizard-panel id="idPanel1">
    ...
  </wizard-panel>
  <wizard-panel id="idPanel2">
    ...
  </wizard-panel>
</wizard>

La navegación suele gestionarse con botones como estos:

<button label="BUTTON_PREVIOUS" icon="chevron-circle-left" id="BkStep1">
  <button-action type="prev-step" target="idWizard"/>
</button>
<button label="BUTTON_NEXT" icon="chevron-circle-right" id="FwStep3" style="btn-primary">
  <button-action type="validate" target="idPanel2"/>
  <button-action type="next-step" target="idWizard"/>
</button>

Más información en la API de wizard.

Diálogos

Los diálogos son útiles para acciones secundarias concretas o para información adicional.

<dialog id="idDialog" modal="true" style="normal" label="TITLE_DIALOG" icon="print" help="HELP_DIALOG">
  <tag type="div" style="modal-body row">
    ...
  </tag>
  <tag type="div" style="modal-footer">
    ...
  </tag>
</dialog>

En las plantillas window, coloque los diálogos en source="modal" y ábralos con una acción de botón:

<button id="openDialog" label="BUTTON_OPEN_DIALOG" icon="floppy-o">
  <button-action type="dialog" target="idDialog" />
</button>

Consulte la API de dialog.

Includes

Utilice include cuando quiera reutilizar un source de otra pantalla en lugar de duplicar el mismo fragmento.

<include target-screen="screenName" target-source="sourceName" />

Es útil para diálogos compartidos o fragmentos de interfaz repetidos.

warning

Evite colisiones de identificadores entre el fragmento incluido y la pantalla actual. El contenido reutilizado con identificadores duplicados puede romper la pantalla.

Consulte la API de include.

Qué hacer a continuación

Una vez que existe la estructura de la pantalla, el siguiente paso habitual es añadir componentes de entrada y de datos:

Continúe con awe-103 para criterios, grids y gráficos.
Utilice awe-106 cuando la pantalla necesite acciones y dependencias.
Tenga a mano la documentación de la API para consultar todos los atributos en lugar de sobrecargar el recorrido del tutorial.

Ruta rápida​

Antes de empezar​

Paso 1: Cree el archivo de la pantalla​

Paso 2: Añada los textos de la pantalla en los archivos de locale​

Paso 3: Añada la pantalla al menú​

Paso 4: Elija las áreas de pantalla adecuadas​

Paso 5: Construya el diseño con los componentes básicos​

Añada estructura HTML sencilla con tag​

Agrupe contenido relacionado con window​

Controle la expansión y las áreas estáticas​

Paso 6: Añada los principales contenedores interactivos​

Botones​

Pestañas​

Asistentes​

Diálogos​

Includes​

Qué hacer a continuación​