Crear una plantilla de control
Para crear una plantilla de control siga estos pasos:
1.En el Panel Páginas haga clic en el icono Agregar página y seleccione Agregar plantilla de control (imagen siguiente).
2.Haga doble clic en la plantilla de control nueva que se añade a la lista (imagen siguiente) y cámbiele el nombre como prefiera. El paso siguiente será declarar los parámetros y definir las variables de la plantilla de control.
Parámetros y variables
Los parámetros permiten usar valores dinámicos o estáticos dentro del alcance de la plantilla de control al instanciar esa plantilla. Tanto los parámetros como las variables se declaran en la plantilla de control. La diferencia principal entre unos y otras es que, mientras los valores de las variables se definen en la plantilla de control, los valores de los parámetros se definen en la página en cuestión y pasan a los parámetros de la plantilla de control cuando esta se instancia.
Si quiere declarar parámetros y/o variables en una plantilla de control, en el panel Páginas (imagen anterior), haga clic en el botón Más opciones (ubicado a la derecha del nombre de la plantilla de control). En el cuadro de diálogo "Parámetros" que aparece (imagen siguiente), añada el parámetro o la variable (haciendo clic en el icono de la barra de herramientas Agregar parámetro o Agregar variable, en la parte superior izquierda del panel correspondiente) y el nombre correspondiente (haga doble clic en el parámetro o la variable para editar el nombre).
Parámetros
Marque la casilla Opcional de un parámetro si quiere que este no sea obligatorio. Si un parámetro es obligatorio pero no recibe el valor correspondiente en tiempo de ejecución, se produce un error. Si en el marcador de posición que emite la llamada el valor de un parámetro se ha definido con una expresión XPath, entonces esta expresión se evalúa en el contexto del marcador de posición. La propiedad Control XPath Context del marcador de posición que instancia la plantilla del control no cambia el nodo de contexto
Variables
Para introducir el valor de una variable (dinámica o estática) haga doble clic en el campo Valor de la variable e introduzca una expresión XPath adecuada.
Tenga en cuenta esta información sobre cómo se evalúan las expresiones XPath de los parámetros y las variables:
•el contexto de las expresiones XPath será el nodo de contexto definido en la propiedad Control XPath Context del marcador de posición que emite la llamada.
•esta expresión XPath para generar valores de variables puede usar los parámetros de esa plantilla de control, así como las variables definidas anteriormente en la lista de definiciones de variables. Por ejemplo: si una plantilla de control tiene los parámetros \$a, \$b, \$c y las variables \$x, \$y, \$z (en ese orden), entonces la variable \$y puede usar estos parámetros y variables para generar su valor: \$a, \$b, \$c, \$x (pero no \$z).
Una vez haya terminado de declarar los parámetros y las variables para la plantilla de control, haga clic en Aceptar. Los parámetros que declare aparecen en el panel Páginas, como se ve en la plantilla DataWithParams, en la imagen siguiente. Puede editar la lista de parámetros/variables de una plantilla de control en cualquier momento; para ello haga clic en el botón Más opciones de la plantilla de control para abrir el cuadro de diálogo "Parámetros".
| Nota: | para cambiar el orden de los parámetros y las variables arrástrelos hasta la ubicación que prefiera. |
| Nota: | si cambia el orden de los parámetros debe asegurarse de que el orden es correcto en la llamada a la plantilla de control (que se hace con los controles Marcador de posición). Para ello: (i) haga clic con el botón derecho en la plantilla de control y seleccione Lista de datos de uso; (ii) por cada entrada (la lista aparece en el Panel "Listas") compruebe si la plantilla de control se ha seleccionado con la lista desplegable o con una expresión XPath; (iii) si la plantilla se ha seleccionado con una expresión XPath y sus parámetros se seleccionan con una expresión matriz (en lugar de con una expresión de asignación), entonces asegúrese de que el orden de los parámetros en la matriz es el mismo que el de la lista de definiciones de parámetros del cuadro de diálogo "Parámetros" (imagen anterior). |
Contenido de la plantilla de control
Para mostrar el lienzo de diseño de la plantilla, seleccione la plantilla de control en el panel Páginas (imagen anterior). El lienzo de diseño aparece en la Vista Diseño. Aquí puede configurar y diseñar un conjunto de controles, igual que lo haría para una página normal. Puede usar controles, acciones, nodos de fuente de página y otros componentes.
Tenga en cuenta que:
•Cuando se instancia la plantilla de control solo se muestra el primer control visible en orden secuencial. (Un control visible es aquel cuya propiedad Visible está establecida en true.) Esto permite crear varios controles dentro de una plantilla y determinar cuáles de ellos se usan; para ello puede usar expresiones XPath condicionales en la propiedad Visible de los controles correspondientes. El control que se usa es el primero que tenga una propiedad Visible que evalúe en true.
•Si quiere mostrar varios controles cuando se instancie una plantilla de control debe agregarlos dentro de la celda de un control Tabla con filas o columnas que se repiten, ya que la tabla cuenta como un control único. En la imagen de más abajo puede ver que se ha añadido un control a cada una de las celdas de una fila de tabla que se puede repetir. Las tablas con columnas y filas que se repiten también se usan en los proyectos de ejemplo. Sin embargo, tenga en cuenta que no puede añadir tablas que se repiten (en las que se repite la tabla entera).
•Si necesita usar un nodo de una de las fuentes de página del diseño y la fuente de página no aparece en el panel "Fuentes de página", entonces puede agregar la fuente de página con el icono Agregar fuente.
•En el diseño de la plantilla de control también puede usar los parámetros y las variables que declaró para la plantilla de control. Por ejemplo, en la plantilla de control DataWithParams que aparece en la imagen siguiente se ha creado un control Tabla con una única fila de siete celdas, cada una de las cuales tiene una etiqueta. Cada una de esas etiquetas tiene un valor Texto que se genera con una expresión XPath que selecciona un parámetro o una variable. Los valores del parámetro los suministra la página en la que se origina la llamada; estos valores son el texto de las etiquetas. Esta plantilla de control se puede usar en distintas ubicaciones y las etiquetas pueden tener distintos textos en función de los valores de parámetro que se pasen a la plantilla desde la página que hace la llamada.
Puede configurar los controles en una plantilla de control igual que como suele configurar estos controles (con sus propiedades y hojas de estilos).
Una vez haya creado la plantilla de control como se describe más arriba ya puede usarla en páginas de nivel superior y subpáginas, además de en las propias plantillas de control.
Consulte Proyectos de ejemplo para ver ejemplos de cómo usar las plantillas de control.
El nodo de contexto de las plantillas de control
El nodo de contexto de una plantilla de control será el nodo de contexto del control Marcador de posición que llama a la plantilla. Si quiere cambiar el nodo de contexto puede indicar uno nuevo con la propiedad Control XPath Context del marcador de posición que emite la llamada. Para ello debe saber cuál es el nodo de contexto porque todas las expresiones XPath de la plantilla de control deben funcionar correctamente dentro de este nodo de contexto. Si tiene pensado reutilizar la plantilla de control en varias ubicaciones del diseño, asegúrese de que las expresiones XPath de la plantilla de control son correctas en cada uno de estos contextos.
Editar los parámetros y las variables de las plantillas de control
Puede editar los parámetros y las variables de una plantilla de control (agregar nuevo/a, eliminar selección, modificar propiedades de) en cualquier momento. Para ello haga clic en el botón Más opciones de la plantilla de control para abrir el cuadro de diálogo "Parámetros" correspondiente. Este botón se encuentra a la derecha del nombre de la plantilla de control en el panel Páginas (imagen siguiente).