construcción de componente basado en fluid viewhelper y fedext
TRANSCRIPT
Construcción de componente basado en Fluid Viewhelper y
FEDext
Enero 2014
Centro de Estudios de Ingeniería de Sistemas
CEIS-UFRO
http://www.ceisufro.cl/
Francisco Llanquipichun Garcia
@F_Llanquipichun
Enero 2014
Índice de contenidos1 Introducción...............................................................................................................................1
2 Requerimientos previos.............................................................................................................1
3 Instalación del Framework.........................................................................................................1
4 Configuración del Framework....................................................................................................2
5 Creación de la Extensión............................................................................................................2
5.1 Construcción de la estructura de carpetas y archivos........................................................2
5.2 Archivos de configuración..................................................................................................3
5.2.1 ext_tables.php............................................................................................................3
5.2.2 ext_icon.gif.................................................................................................................3
5.2.3 ext_emconfig.php.......................................................................................................3
5.2.4 setup.txt.....................................................................................................................4
5.3 Creación de un Fluid Viewhelper........................................................................................6
5.4 Creación de un Fluid Flexform............................................................................................7
6 Instalación de la extensión en TYPO3.........................................................................................9
Índice de tablasTabla 1: lista de extensiones de FEDext.............................................................................................1Índice de ilustraciones Ilustración 1: instalación de extensión...............................................................................................2Ilustración 2: configuración de flux....................................................................................................2Ilustración 4: archivo ext_tables.php.................................................................................................3Ilustración 3: estructura de carpetas y archivos.................................................................................3Ilustración 5: archivo ext_emconfig.php............................................................................................4Ilustración 6: archivo setup.txt...........................................................................................................5Ilustración 7: sintaxis archivo setup.txt..............................................................................................5Ilustración 8: referencias a CSS y JS en archivo setup.txt...................................................................5Ilustración 9: estructura de Viewhelper.............................................................................................6Ilustración 10: ejemplo de método render()......................................................................................7Ilustración 11: código HTML resultante.............................................................................................7Ilustración 12: estructura de un Fluid Flexform.................................................................................8Ilustración 13: sintaxis de referencia a una clase Fluid.......................................................................8Ilustración 14: habilitar una extensión...............................................................................................9Ilustración 15: acceder a ‘Edit the whole template record’................................................................9Ilustración 16: include statics...........................................................................................................10Ilustración 17: limpieza de caches....................................................................................................10Ilustración 18: representación de Fluid Flexform en back-end........................................................11
Ilustración 19: representación de Fluid flexform configuration en back-end...................................12
1 IntroducciónEsta guía está orientada a la construcción de componentes gráficos parametrizables y reutilizables, para su uso en el CMS TYPO3.
Objetivos de la guía:
Instalación del framework FEDext para TYPO3 Construcción de una extencion basada en Viewhelpers y Fluid Flexforms Construcción de un Viewhelper básico Construcción de un Fluid Flexform Instalación y configuración de una extensión basada en FEDext.
2 Requerimientos previosPara el correcto funcionamiento de los componentes es necesario contar con una serie de requerimientos previos, que se consideran de conocimiento general y no forman parte de la explicación de este tutorial:
Instalación de TYPO3: requiere el uso de la última versión estable de TYPO3 CMS actualmente esta es la versión 6.1. La versión debe tener soporte de Extbase y Fluid, idealmente también soporte de archivos FAL.Link de descarga: http://typo3.org/download/
3 Instalación del FrameworkSe utilizara el framework Fluid Powered TYPO3 (https://fedext.net/), para su instalación se deben descargar e instalar a través de Extension manager las siguientes extensiones de TYPO3:
Nombre EXT Link en repositorio de TYPO3
css_styled_content instalado en typo3 por defecto
Flux Flux: Fluid FlexForms http://typo3.org/extensions/repository/view/flux
Fluidpages Fluid Pages Engine http://typo3.org/extensions/repository/view/fluidpages
Fluidcontent Fluid Content Engine http://typo3.org/extensions/repository/view/fluidcontent
VHS VHS: Fluid ViewHelpers http://typo3.org/extensions/repository/view/vhs
fluidpages_bootstrap Fluid Pages: Twitter Bootstrap Templates
http://typo3.org/extensions/repository/view/fluidpages_bootstrap
fluidcontent_bootstrap Fluid Content: Twitter Bootstrap Elements
http://typo3.org/extensions/repository/view/fluidcontent_bootstrap
Tabla 1: lista de extensiones de FEDext
La instalación de estas extensiones debe seguir el mismo orden de esta lista, ya que existe dependencia entre ellas.
1
La instalación de las extensiones debe realizarse a través de la herramienta Extension Manager ubicada en la interfaz de back-end de TYPO3.
Ilustración 1: instalación de extensión
El formulario para la instalación de una extensión se despliega a través del botón ubicado en la esquina superior izquierda. En el formulario se debe agregar el archivo descargado (.t3x) y presionar el botón Upload!
4 Configuración del FrameworkUna vez instaladas las extensiones, es recomendable hacer los siguientes ajustes de configuración:
En Extension Manager buscamos la extensión Flux: Fluid FlexForms y accedemos a su configuración a través del icono del engranaje.
Ilustración 2: configuración de flux
los campos que se deben modificar son:
Debug Mode [basic.debugMode] -> seleccionar la opcion 1: muetra todos los mensajes de debug en la interfaz de backend.
Development stage rewriting of LLL files [basic.rewriteLanguageFiles] -> activar el checkbox: esto da poder a la extension para leer,editar y guardar archivos LLL, se recomienda tenerlo abilitado solo mientras se esta construllendo una extension ya que eleva los tiempo de procesamiento dramaticamente.
5 Creación de la Extensión
5.1 Construcción de la estructura de carpetas y archivosEsta sección está basada en la documentación de Fluid TYPO3 QuickstartGuide:
https://github.com/FluidTYPO3/documentation/blob/master/QuickstartGuide.md
La extensión se debe crear en el directorio de TYPO3: .\typo3conf\ext\miextension.
2
La estructura de carpetas debe estar construida de la siguiente manera:
En este caso el nombre de la extensión será fluidinfobtn como lo indica el nombre de la carpeta raíz.
En el diagrama además se muestran algunos de los archivos de configuración básicos.
Es muy importante tener presente la importancia de las mayúsculas en los nombre de los archivos y carpetas.
Para agilizar la construcción es posible descargar un proyecto de GitHub con la estructura básica de archivos ya definida.
El proyecto se encuentra actualmente en el siguiente repositorio:
https://github.com/FluidTYPO3/ft3_empty
5.2 Archivos de configuración A continuación se detallaran los diferentes archivos de configuración, sus características y las diferentes configuraciones que son posibles.
5.2.1 ext_tables.phpEste archivo contiene información básica sobre la extensión.
Ilustración 4: archivo ext_tables.php
Por ejemplo el texto Configuracion/Typoscript corresponde al directorio donde se encuntra el archivo de configuración setup.txt y el texto Front-end Search media file corresponde a una descripción general sobre la extensión.
5.2.2 ext_icon.gifEs el icono que se mostrara en la extensión.
5.2.3 ext_emconfig.phpEste archivo contiene información básica sobre la extensión: información sobre el autor, compatibilidad y dependencia, entre otros parámetros.
3
Ilustración 3: estructura de carpetas y archivos
Ilustración 5: archivo ext_emconfig.php
Es importante destacar que en el campo dependencies se especifican las extensiones de las cuales depende la nueva extensión, en este caso se especifican extensiones propias de TYPO3 más las pertenecientes al framework FEDext.
5.2.4 setup.txtEste archivo se encuentra en el fichero Configuration/Typoscript/ y es referenciado por el archivo ext_tables.php.
4
Ilustración 6: archivo setup.txt
La configuración plugin.tx_fluidinfotable.view se encarga de referenciar los diferentes directorios de archivos para template, partial y layout. En todos los casos fuidinfotable se refiere al nombre de la extensión, en el caso que el identificador de la extensión es igual al nombre de la carpeta contenedora, la sintaxis sería la siguiente:
Ilustración 7: sintaxis archivo setup.txt
Dentro de este archivo es posible generar varias configuraciones a travez de Typoscript. La más relevante es posibilidad de configurar la carga de contenido en el <HEAD> de la página. Esto se realiza con los parámetros page.includeJS y page.includeCSS que referencian archivos de tipo Javascript o Css respectivamente.
Ilustración 8: referencias a CSS y JS en archivo setup.txt
En la imagen de ejemplo se observa dos formas diferentes de cargar un archivo: En la línea 9 se carga el archivo directamente desde el directorio de la extensión. La línea 12 y 13 referencian a un archivo externo a la extensión y a TYPO3. Por último la línea 14 obliga a que el archivo sea cargado al principio del <HEAD> antes q cualquier otro archivo javascript.
Es importante destacar que jQueryMigrate es solo un nombre de referencia al archivo y puede ser cambiado por cualquier otro. En el caso de que este nombre es duplicado como en el caso anterior, el archivo es sobrescrito. El nombre de referencia es una constante válida para todas las extensiones de tipo.
5
Además como se puede suponer, el directorio especial para los recursos de front-end se debe situar dentro del directorio ./Resources/Public/, dentro de este es posible la creación de sub directorios para mantener mejor el orden de archivos CSS, JS, imágenes o librerías.
5.3 Creación de un Fluid ViewhelperEl Fluid Viewhelper será el encargado de generar la interfaz grafica de forma dinámica. El archivo se debe crear dentro del directorio de la extensión: ./Classes/ViewHelper/
La estructura del nombre del archivo creado debe ser de la siguiente forma:
MiExtensionViewHelper.php
Donde MiExtension es el nombre del Viewhelper. El nombre debe empezar con mayúscula ya que se trata de una clase PHP y las siguientes palabras deben estar escrita con formato camelCase. El nombre del archivo siempre debe terminar con texto ViewHelper.php como lo muestra el ejemplo.
La estructura de un Viewhelper es la siguiente:
Ilustración 9: estructura de Viewhelper
En el nombre de la clase, extension se refiere a la extensionKey y NombreArchivoViewHelper se refiere al nombre del archivo.
En el ejemplo se observan dos métodos o funciones: InitializeArguments() y render().
Método render(): La clase debe incluir obligatoriamente el método render, que será el encargado de realizar la lógica del Viewhelper. Todos los parámetros de esta función deben estar especificados en forma de comentario especificando que se trata de un parámetro (@param), el tipo de variable (string, boolean, array, mixed, etc) y el nombre de la variable acompañado de una descripción opcional.
6
Ilustración 10: ejemplo de método render()
Como se muestra en la imagen de ejemplo los parámetros con valor por defecto, son considerados opcionales.Este método en particular utiliza otros métodos que se encuentran dentro de la misma clase: renderByBackend() y renderByCode(), para construir el código HTML que retorna el viewhelper. Estos métodos obtienen objetos similares, pero de orígenes distintos:
o renderByBackend(): obtiene en este caso el objeto desde un Fluid Flexform.o renderByCode(): obtiene un objeto desde una clase PHP (InfoButton).
En este documento solo se analizaran los parámetros provenientes de un Fluid Flexfom. El código resultante que genera este viewhelper puede resultar en el siguiente código HTML:
Ilustración 11: código HTML resultante
Método initializeArguments(): es una función opcional o una alternativa más para inicializar los parámetros del viewhelper, su sintaxis se puede observa en la ilustración anterior.
5.4 Creación de un Fluid FlexformEl flexform será el encargado de crear la interfaz de back-end y desplegar la vista en el front-end.
Dentro del directorio ./Resouces/prívate/Templates/Content/ se debe crear un archivo de tipo HTML, que tiene una estructura especial, detallada a continuación:
7
Ilustración 12: estructura de un Fluid Flexform
El Fluid Flexform se divide en tres secciones principales: Configuration, Preview y Main.
Configuration: en el ejemplo esta sección se identifica con la etiqueta fluid <f:section name=”Configuration” > </f:section> Dentro de esta se encuentra todo el contenido del Fluid Flexform que representara la configuración de la extensión por back-end.
Preview: en el ejemplo esta sección se identifica con la etiqueta fluid <f:section name=”Preview” > </f:section> y es la responsable de crear la pre visualización de la extensión en back-end.
Main: en el ejemplo esta sección se identifica con la etiqueta fluid <f:section name=”Main” > </f:section>. Esta sección es la encargada de desplegar el contenido en el front-end, en este caso esta sección será la encargada de generar el contenido a través del Viewhelper que hemos definido.
En la parte superior del Fluid Flexform se encuentra las referencias a los diferentes Viewhelpers que se utilizaran. Para los flexforms es importante que se encuentre referenciado los Tx_Flux_ViewHelpers. La referencia de los Viewhelpers sigue la siguiente regla de acuerdo al nombre de la clase del Viewhelper:
Ilustración 13: sintaxis de referencia a una clase Fluid
Una vez que contamos con los diferentes archivos de la extensión configurados correctamente, será posible instalar y probar la extensión.
8
6 Instalación de la extensión en TYPO3En primer lugar se debe habilitar la extensión desde el Extension Manager buscamos el nombre con el que creamos la extensión y presionamos el icono para habilitar la extensión.
Ilustración 14: habilitar una extensión
Lo siguiente será incluir static Templates, estos se deben incluir en el Template de la página raíz del sitio, ingresando en la opción de Edit the whole template record:
Ilustración 15: acceder a ‘Edit the whole template record’
En la pestaña Includes y en la sección Include static (from extension) se debe agregar la nueva extensión desde el panel Available Items a Selected Items. Esta debe tener el nombre que se le asigno en el archivo ext_tables.php seguido del extensionKey entre paréntesis.
9
Ilustración 16: include statics
Es muy importante recordar limpiar el cache cada vez que agregamos este tipo de componentes. La limpeza de cache se puede realizar presionando el icono del rayo en el menú principal y seleccionando la opción Clear all caches.
Para insertar la extensión como contenido de una página se debe agregar normalmente,
presionando el icono de add new record at this place en la vista del contenido de la página. Se desplegara la ventana de pestañas con los diferentes tipos de extensiones que se pueden utilizar; si el proceso realizado anteriormente ha sido exitoso, entre la pestañas normales aparecerá una nueva con el nombre de FCE.
10
Ilustración 17: limpieza de caches
Ilustración 18: representación de Fluid Flexform en back-end
Los elementos contenidos dentro de esta pestaña representan a las diferentes páginas de contenido que se han creado en forma de Fluid Flexform, como es de suponer es posible crear más de una página de contenido por extensión.
Al selecciona una extensión se desplegar inmediatamente las opciones de configuración. En primer lugar en la pestaña General están las configuraciones por defecto con opciones típicas como: alineación, titulo, el tipo de elemento, etc. Seguido de esto se encuentra una sección especial generada por el Fluid Flexform, específicamente la parte del Flexform delimitada por la etiquetas configuration.
11
Ilustración 19: representación de Fluid flexform configuration en back-end
Finalmente la extensión configura será desplegada en el front-end de la pagina, mostrando el contenido que se ha establecido en el Fluid Flexform y en el viewhelper.
12