Descargar - K2BTools

Manual de usuario 1.0
K2BWebPanelBuilder Beta1
1
Introducción: ______________________________________________________ 3
2
Pautas previas: _____________________________________________________ 3
2.1
Pautas previas antes de la aplicación K2BWebPanelBuilder _________________ 3
2.2
Funcionamiento de la herramienta ______________________________________ 3
2.2.1
2.2.2
2.2.3
2.2.4
2.3
2.3.1
2.3.2
2.3.3
2.3.4
3
Variables ________________________________________________________________ 4
Eventos _________________________________________________________________ 5
Rules ___________________________________________________________________ 7
WebForm ________________________________________________________________ 7
Nomenclatura del WebPanel Builder ____________________________________ 8
Variables ________________________________________________________________ 8
Eventos _________________________________________________________________ 8
Rules ___________________________________________________________________ 8
WebForm ________________________________________________________________ 8
Lenguaje de especificación de los WebPanels ____________________________ 9
Nodo WebForm __________________________________________________________________ 9
Nodo Grid _____________________________________________________________________ 10
4
Avanzado ________________________________________________________ 14
4.1
Modificación de la interfaz ____________________________________________ 14
1
2
1 Introducción:
K2BWebPanelBuilder fue creado con el objetivo de poder desarrollar aplicaciones
WEB más rápido, escalables, de fácil mantenimiento y propagación de cambios. Desde
el punto de vista del desarrollador la herramienta permite abstraerse de complejidades
inherentes al diseño de los WebPanels presentes en Genexus, de esta forma puede
enfocarse en la parte funcional de su aplicación dado que los problemas comunes en el
desarrollo son solucionados por el patrón.
La idea del web panel builder es poder generar y mantener desde un nivel de abstracción
mayor, aquellas pantallas que no tienen porqué cumplir con el patrón workwith. Mediante
el uso del web panel builder el desarrollador, no debería trabajar más en el web form de
los web panels sino especificar este en un nivel de abstracción superior.
Para una guía de uso rápido de esta herramienta, recomendamos en la sección
capacitación -> descargas, descargar el taller de las k2btools, en la que se encuentra un
ejercicio que explica paso por paso la construcción de un panel usando esta aplicación.
2 Pautas previas:
En esta sección se presentarán las consideraciones a tener presentes antes de comenzar a
utilizar la herramienta.
2.1 Pautas previas antes de la aplicación K2BWebPanelBuilder
Dado que la herramienta es una extensión de Genexus X Evolution 1, esta debe ser
instalada sobre dicha versión de Genexus.
Se recomienda que la propiedad Dynamic K2B Web Form Pattern Update sea seteada en
No. De esta forma el pattern se comportará mas estilo diseñador y se actualizara
solamente al salvar el objeto si la casilla Apply this pattern on save esta seleccionada.
2.2 Funcionamiento de la herramienta
Consideraciones más importantes a tener en cuenta antes de empezar a utilizar la
herramienta:
3
1) El pattern actualmente no genera ningún objeto, solamente actualiza el WebPanel
al que se le aplica el patrón. Notar que se comporta como una parte nueva del
WebPanel, en el futuro se podrá cambiar a extensión.
2) Las partes del WebPanel que hacen uso del WebPanelBuilder son mantenidas
tanto por el patrón como por el usuario. El WebFom es la única parte que hasta el
momento es mantenida únicamente por el editor. Esto implica que el usuario
puede agregar sus propios eventos, variables, subrutinas, reglas del WebPanel
siempre y cuando las mismas cumplan con la nomenclatura adecuada (ver
Nomenclatura WebPanelBuilder).
a. WebForm: será sobrescrito en caso de ser necesario cada vez que se
aplique el patrón. Por lo tanto la única forma de agregar contenido al
WebForm del WebPanel es mediante su especificación en la instancia del
patrón.
b. Eventos: se pueden agregar subrutinas, eventos de usuario, agregar
comentarios; modificar la posición, lugar u orden de los eventos y
subrutinas; etc. En caso de modificar una subrutina o evento perteneciente
al editor (ver nomenclatura), al salvar el objeto esos cambios no tendrán
efecto en el WebPanel, es decir se sobrescribe los eventos pertenecientes
el editor (ya sean de Internos o del Editor).
3) Las propiedades del WebPanel se modifican directamente en el mismo, un
ejemplo de esto sería cambiar la propiedad Type a Component para que pueda ser
utilizado como WebComponent o setearle un tema de usuario son algunos
ejemplos. La única propiedad forzada por el patrón es la propiedad Automatic
Refresh la cual se modifica a No.
4) El editor genera una cantidad importante de comentarios de ayuda al usuario de
cómo trabajar con la herramienta, en el futuro esto se podrá configurar para no
generar dichos comentarios.
2.2.1 Variables
Como se ha mencionado anteriormente las variables son mantenidas tanto por el editor
como por el usuario.
Que sean mantenidas por el editor significa que el editor agrega, modifica y borra
variables a partir de la metadata que especifican los componentes del WebPanel.
El editor maneja tres tipos de variables: variables del editor, variables internas, variables
de usuario.
4
Variables del Editor: Son mantenidas por el editor y su nombre siempre comienza con
E_. El usuario puede hacer referencia a estas variables y modificar su valor. Puede ocurrir
que la variable esté referenciada por un evento de usuario y el editor intente borrarla
dado que la especificación que la generaba se eliminó. En este caso el objeto no salvará y
habrá que eliminar la referencia de forma manual. Este caso y otros casos similares van a
ser contemplados en futuras versiones, dando la posibilidad al desarrollador a mantener la
variable, borrar el fragmento de código que referencia la variable o comentarlo.
Variables Internas: También son mantenidas por el editor, a diferencia de las anteriores,
el usuario no puede modificar su valor. El nombre siempre posee I_ como prefijo.
Un ejemplo de este tipo de variable es I_HasNextPage la cual determina si una grilla
tiene una pagina siguiente y luego es utilizada por el editor para determinar si es visible el
botón de next page asociado a una grilla. Otro ejemplo podría ser I_GridLoadCount la
cual lleva un conteo de la cantidad de registros cargados en una grilla, variable que puede
ser consultada por el usuario pero no modificada.
Variables de Usuario: Son creadas, modificadas y eliminadas exclusivamente por el
desarrollador. En la mayoría de los casos van a ser variables destinadas a lógica de
negocio. El diseñador intenta minimizar la definición de estas variables ofreciendo un
conjunto de variables de ayuda para tareas comunes en el diseño de un WebPanel.
Es importante aclarar que estas variables no pueden comenzar con I_ ni con E_ en dicho
caso el editor las considerará como internas o del Editor y las eliminará.
2.2.2 Eventos
El patrón intenta generar la mayor parte de los eventos del WebPanel, dejando algunas
subrutinas y eventos para que el usuario las programe.
Existen tres tipos de bloques de código que el diseñador reconoce:
Eventos y Subrutinas de Editor: Son eventos mantenidos por el editor que
normalmente invocan a algún método de usuario para extender o cambiar su
funcionamiento.
Algunos ejemplos sencillos de estos eventos pueden ser el evento Start, refresh, Load de
Grillas, Eventos que atienden las acciones en grilla, acciones de paginado, evento Search,
eventos de acciones Standalone etc. Además de los eventos anteriores todos los que su
nombre comience con E_ pertenecen a esta categoría.
También dentro de este grupo encontramos subrutinas que son de ayuda para el
programador, la tendencia es que a medida que se siga desarrollando la herramienta
existan mas de estas subrutinas facilitando el trabajo al desarrollador. Estas últimas en
lugar de invocar a subrutinas de usuario (como lo hacen los eventos del editor en la
mayoría de los casos) deben ser invocadas por código del desarrollador.
5
Un ejemplo de este tipo de subrutinas puede ser las dos subrutinas siguientes que el
diseñador crea cuando se tiene multirrow en una grilla (acción asociada a una grilla):
Sub 'E_ResetMultirowIterator(CountryGrid)'
&I_MRowIterator_CountryGrid = 1
EndSub
Sub 'E_GetNextMultirow(CountryGrid)'
&E_MRowHasNext_CountryGrid = False
&I_MRowCurrentIndex = 1
For Each line in CountryGrid
If &E_CountryGrid_Item_Selected = True
If &I_MRowCurrentIndex = &I_MRowIterator_CountryGrid
&I_MRowIterator_CountryGrid += 1
&E_MRowHasNext_CountryGrid = True
exit
EndIf
&I_MRowCurrentIndex += 1
EndIf
EndFor
EndSub
Estos métodos son utilizados para iterar sobre las filas seleccionadas de una grilla.
Cuando el desarrollador agrega una acción MultiRow que se encuentre bajo el nodo Grid
el diseñador genera automáticamente las subrutinas descriptas arriba, además genera el
procedimiento
Event 'E_ViewCountriesCitiesMultirow' que atiende al evento click y la subrutina de
usuario 'U_ViewCountriesCitiesMultirow' en la cual el desarrollador podrá poner su
código específico y funcional para realizar un comportamiento específico (invocar a un
procedimiento, habilitar o deshabilitar controles, cambiar registros en la base de datos,
modificar cualquier estado, etc).
Notar que el desarrollador no se preocupa en la seguridad de la acción, ni en validar que
realmente se haya seleccionado alguna fila, esta tarea es realizada por el diseñador y en
caso de cambiar la propiedad MultiRow de la acción a single, cambiar la seguridad de la
acción o otra configuración se actualizará automáticamente dicho evento.
Event 'E_ViewCountriesCitiesMultirow'
// ---- K2BTools - Do Not Change, Editor Method ---Do 'E_ResetMultirowIterator(CountryGrid)'
Do 'E_GetNextMultirow(CountryGrid)'
If &E_MRowHasNext_CountryGrid = False
msg("Error : Debe seleccionar alguna línea")
Else
Do 'E_ResetMultirowIterator(CountryGrid)'
Do 'U_ViewCountriesCitiesMultirow'
EndIf
EndEvent
6
Sub 'U_ViewCountriesCitiesMultirow'
// ---- K2BTools - To Be Completed By User ---// Do 'E_GetNextMultirow(CountryGrid)'
// Do While &E_MRowHasNext_CountryGrid = True
//
<Specific User Code, you can use all grid variables
and attributes>
//
Do 'E_GetNextMultirow(CountryGrid)'
// EndDo
EndSub
Eventos y Subrutinas de Usuario (creadas y mantenidas por el diseñador, el usuario
tiene total control sobre su contenido):
El diseñador generará un conjunto de subrutinas para que el desarrollador agregue su
propio código y brindarle flexibilidad en sus soluciones, estas subrutinas poseen U_
como prefijo del nombre.
Por ejemplo para cada grilla el diseñador genera y mantiene el código del Load y para
cada registro a cargar invoca la subrutina Do 'U_LoadRowVars(<GridName>)' la cual se
puede utilizar para realizar diversas tareas como, sumar todos los valores de alguna
columna de la grilla para calcular algún total, modificar la variable a cargar en la grilla,
cancelar la carga de una línea o registro, salir de la carga de la grilla, etc.)
Eventos y Subrutinas creados y mantenidos por el usuario
Estos eventos o subrutinas que son definidos por el usuario, el diseñador los dejara en su
lugar y forma correspondiente cuando se generen las demás secciones de los eventos.
2.2.3 Rules
El patrón actualmente no genera ninguna regla. El usuario puede hacer los cambios que
considere necesarios.
2.2.4 WebForm
Esta parte es totalmente actualizada por el patrón. Cualquier cambio que el usuario
realice se sobrescribirá cuando se aplique el patrón.
7
2.3 Nomenclatura del WebPanel Builder
2.3.1 Variables
Variables del Editor: Poseen el prefijo E_ en el nombre
Variables Internas: Poseen el prefijo I_ en su nombre
Variables de usuario: Son variables que no se corresponden a ninguna de las dos
anteriores.
2.3.2 Eventos
Eventos o Subrutinas del Editor:
Poseen el prefijo E_, también incluye los eventos Start, Refresh, Load de grillas, e
eventos que comienzan con nombres de variables internas (&I_ como prefijo, ejemplo
&I_OrderedBy_GridX.IsValid).
Eventos o subrutinas de Usuario:
El nombre asociado a estos eventos comienza con U_, es decir posee U_ como prefijo.
Eventos o Subrutinas Nuevos:
Subrutinas que no están abarcadas en ningún caso anterior.
2.3.3 Rules
Actualmente el WebPanelBuilder no especifica ninguna regla.
2.3.4 WebForm
Los contoles del webForm siguen los mismos lineamientos que las variables con la única
diferencia que actualmente todos los controles son mantenidos por el patrón.
Controles de Editor: Poseen el prefijo E_ en el nombre.
Controles Internos: Poseen el prefijo I_ en su nombre.
8
3 Lenguaje de especificación de los WebPanels
El lenguaje de especificación tiene una estructura de árbol. Una instancia de este árbol
abstrae la definición del WebForm (la cual se puede ver naturalmente en el árbol),
además a partir de una instancia se genera gran parte del código de los eventos (explicado
más adelante) y la mayor parte de las variables presentes en el WebPanel.
Nodo WebForm
En la raíz está presente el nodo WebForm, el cual permite la configuración de
propiedades generales del WebPanel.
La propiedad Title se puede utilizar para agregar un título. En caso de que esta propiedad
se encuentre vacía el diseñador no agregará dicha sección al webForm.
NeedErrorViewer es usada para indicar cuando no se requiere tener en el webpanel un
control error viewer, esto se puede dar por que no se necesite o por que el
WebComponent que se está diseñando estará contenido en otro objeto que si contenga
una sección para mostrar mensajes en pantalla.
Para configurar la seguridad de acceso al objeto se puede hacer uso de la propiedad
ActivityName. En caso de setearle un nombre a la propiedad se generará el siguiente
código en el evento Start.
Del nodo raíz se tiene como hijos los nodos Attributes, Grid, QueryObject,
WebComponent los cuales se pueden utilizar para agregar información de la aplicación
al WebPanel y los nodos Columns, LineSeparator, Group que son de utilidad al
momento de darle formato y diseño al HTML.
9
Nodo Grid
Para especificar grillas se utiliza el nodo Grid, en este nodo se determinan los filtros
(nodo Filters), ordenes (nodo Orders), condiciones de carga de usuario (nodo
Conditions), acciones (nodo Actions). Los ítems de la grilla como atributos, variables y
acciones se especifican bajo nodo Columns.
El editor soluciona problemas comunes que se dan en el momento agregar grillas en un
WebForm: agregar la grillas con sus atributos y/o variables en el formulario, el combo
con los ordenes, los controles de paginado, el botón de búsqueda, eventos de paginado,
eventos de carga de la grilla, condiciones de carga, inicializar las variables, acciones y
links, etc.
Las propiedades del nodo Grid son:
Name: Nombre de la Grilla debe ser único dentro del conjunto de grillas y controles que
se especifican para el WebPanel. El diseñador a partir de la grilla genera un conjunto de
variables para resolver el paginado, los filtros, órdenes y otras problemáticas asociadas a
la grilla.
Theme: Tema de la grilla.
Page: Máxima cantidad de registros que se pueden cargar en la grilla.
DefnedBy: En caso de grillas sin tabla base se puede especificar atributos para determinar
la navegación. (Únicamente utilizado en grillas “Grillas con ForEach inferido sin Tabla
Base”.)
10
Existen tres clases de grillas:
• Grillas con tabla base.
• Grillas sin tabla base en las cuales se puede inferir un foreach para el evento load
• Grillas sin tabla base.
3.1.1.1 Grillas con tabla Base
Son todas aquellas grillas que poseen al menos un atributo en la grilla (dentro del nodo
Columns).
3.1.1.2 Grillas con ForEach inferido sin Tabla Base
En caso de tener algún orden, alguna variable bajo el nodo Filtres con la propiedad
Condition seteada o alguna variable en grilla basada en un atributo y además que tenga
la propiedad LoadFromAttribute = True el for each de la grilla será generado
automáticamente como se muestra a continuación.
11
Este tipo de grillas pueden contener variables que no pueden ser inferidas, ya sea por que
tenga la propiedad LoadFromAttribute = False (basada en atributo) o por que no este
basada en un atributo. En este caso se tendrá que brindar al desarrollador la posibilidad de
cargar dichas variables, para esto el editor genera el método
‘U_LoadRowVars(<GridName>)’ adonde el desarrollador puede escribir su código
particular y pueda modificar el comportamiento de la carga de la grilla. Este método se
invoca para cada registro a cargar perteneciente al foreach, antes de invocar el evento se
setean las variables:
&I_GridLoadCount += 1
&E_GridLoadRow = True
La primera se utiliza para contar los registros que se cargan, como se puede apreciar es
una variable interna por lo cual el usuario puede consultar su valor pero no modificarla.
La variable E_GridLoadRow es del editor y por lo tanto el usuario puede modificar su
valor, en caso de setearla en false el registro no se cargara. Esta variable puede ser de
utilidad para realizar filtros complejos de carga. Notar que antes de invocarse el método
el editor la setea en true, por lo que no necesita ser asignada nuevamente si se quiere
cargar el registro.
Sub 'U_LoadRowVars(CityGrid)'
12
//
//
//
//
//
---- K2BTools - To Be Completed By User ---&I_GridLoadCount - 1: Number of record loaded in grid (Do not
change variable value)
&E_GridLoadRow: Set to False when you don't want to load
current record
EndSub
Todo el código y la interfaz referente al paginado, órdenes y filtros son totalmente
generados por el editor.
A continuación vemos ejemplo de la generación de este código para este tipo de
grilla:
13
3.1.1.3 Grillas sin tabla Base
Este tipo de grilla ocurre cuando no se tiene ningún attributo en grilla (nodo columns) o
por que no se pudo inferir un foreach desde la especificación de la misma. En estos casos
el editor intenta subsanar los problemas de carga de la grilla, paginado, etc, mediante el
siguiente evento load:
Event CountryGrid.Load
// ---- K2BTools - Do Not Change, Editor Method ---&I_GridLoadCount = 0
&I_HasNextPage = False
&E_Exit = False
Do While True
&I_GridLoadCount += 1
If (&I_GridLoadCount > 10 * &E_CountryGrid_CurrentPage)
&I_HasNextPage = True
exit
EndIf
Do 'U_LoadRowVars(CountryGrid)'
If (&E_Exit = True)
exit
EndIf
If (&I_GridLoadCount > (10 * (&E_CountryGrid_CurrentPage 1)) and &I_GridLoadCount <= (10 * &E_CountryGrid_CurrentPage))
Load
EndIf
EndDo
Do 'E_UpdateControls(CountryGrid)'
EndEvent
Como se puede apreciar en el evento se realiza un Do While en el cual se controla la
carga de la grilla para esto el evento load mantenido por el diseñador invoca la subrutina
'U_LoadRowVars(<GridName>)' en la cual se deberá cargar las columnas de la misma.
Para terminar la carga se deberá setear la variable &E_Exit a true, en caso de no setear
esta variable la ejecución entrara en un loop infinito.
4 Avanzado
4.1 Modificación de la interfaz
Dado que la interfaz generada no tiene un formato estándar (es decir depende fuertemente
de la especificación y de que controles estén presentes), no se pudo desarrollar el mismo
mecanismo (objeto layout) presente en los otros patrones para modificar la interfaz.
14
Dada esta limitante y la necesidad de customizar la interfaz se brinda otro mecanismo,
que está basado en dkt’s. Para esto el generador invoca un dkt antes y otro después de la
construcción de ciertas regiones de la UI.
Cada dkt recibe como parámetro el nodo de la instancia a generar (grilla, filtros ,
webComponent, embedded page, etc) como se muestra a continuación:
<%@ Property Name="PatternInstanceElement"
Type="Artech.Packages.Patterns.Objects.PatternInstanceElement" %>
En el mismo se pueden importar los dll (ensamblados) que sean pertinentes y utilizar los
namespace (espacio de nombres) deseados.
La idea de los dkt (Before… y After…..) es generar HTML que contenga una sección
específica.
Como ejemplo se mostrará como se crea el contenedor a la sección de filtros de las
grillas.
<%@ Template Language="C#" TargetLanguage="GX" Description="Before Grid
Filters" %>
<%@ Property Name="PatternInstanceElement"
Type="Artech.Packages.Patterns.Objects.PatternInstanceElement" %>
<div class="Section_FiltersHeader" >
<%= WebForm.TextBlock(String.Empty, "TextBlock_FilterTitleED",
"Filters") %>
</div>
<div class="Section_Filters">
Se puede observar que en el primer div se agrega un textblock con caption Filters y
theme TextBlock_FilterTitleED.
Luego se abre otro div el cual contendrá la seccion de filtros generada por el diseñador (el
segundo tag html <div>), que se deberá cerrar el dkt AfterGridFilters, como vemos a
continuación:
<%@ Template Language="C#" TargetLanguage="GX" Description="After Grid
Filters" %>
<%@ Property Name="PatternInstanceElement"
Type="Artech.Packages.Patterns.Objects.PatternInstanceElement" %>
</div>
Los dkt’s se pueden encontrar en la carpeta
<genexusDir>\Packages\Patterns\K2BWebForm\Templates, la nomeclatura de
los mismos es Before<ComponenteInterfaz>.dkt y
After<ComponenteInterfaz>.dkt.
15
16