Manual de usuario 1.0 K2BWebPanelBuilder Beta1

Transcripción

1 Manual de usuario 1.0 K2BWebPanelBuilder Beta1

2 1 Introducción: 3 2 Pautas previas: Pautas previas antes de la aplicación K2BWebPanelBuilder Funcionamiento de la herramienta Variables Eventos Rules WebForm Nomenclatura del WebPanel Builder Variables Eventos Rules WebForm 8 3 Lenguaje de especificación de los WebPanels 9 Nodo WebForm 9 Nodo Grid 10 4 Avanzado Modificación de la interfaz 14 2

3 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

4 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 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

5 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á 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

6 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

7 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 Rules El patrón actualmente no genera ninguna regla. El usuario puede hacer los cambios que considere necesarios 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

8 2.3 Nomenclatura del WebPanel Builder 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 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 Rules Actualmente el WebPanelBuilder no especifica ninguna regla 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

9 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

10 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

11 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 Grillas con tabla Base Son todas aquellas grillas que poseen al menos un atributo en la grilla (dentro del nodo Columns) 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

12 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

13 // ---- 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

14 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

15 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 16