2. Enero 2014
Centro de Estudios de Ingeniería de Sistemas
CEIS-UFRO
http://www.ceisufro.cl/
Francisco Llanquipichun Garcia
@F_Llanquipichun
francisco.llanquipichun@gmail.com
3. Índice de contenidos
1 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 tablas
Tabla 1: lista de extensiones de FEDext.............................................................................................. 1
Índice de ilustraciones
Ilustración 1: instalación de extensión................................................................................................ 2
Ilustración 2: configuración de flux..................................................................................................... 2
Ilustración 4: archivo ext_tables.php.................................................................................................. 3
Ilustración 3: estructura de carpetas y archivos ................................................................................. 3
Ilustración 5: archivo ext_emconfig.php............................................................................................. 4
Ilustración 6: archivo setup.txt............................................................................................................ 5
Ilustración 7: sintaxis archivo setup.txt............................................................................................... 5
Ilustración 8: referencias a CSS y JS en archivo setup.txt ................................................................... 5
Ilustración 9: estructura de Viewhelper.............................................................................................. 6
Ilustración 10: ejemplo de método render()....................................................................................... 7
Ilustración 11: código HTML resultante.............................................................................................. 7
Ilustración 12: estructura de un Fluid Flexform.................................................................................. 8
Ilustración 13: sintaxis de referencia a una clase Fluid....................................................................... 8
Ilustración 14: habilitar una extensión................................................................................................ 9
Ilustración 15: acceder a ‘Edit the whole template record’................................................................ 9
Ilustración 16: include statics............................................................................................................ 10
Ilustración 17: limpieza de caches..................................................................................................... 10
Ilustración 18: representación de Fluid Flexform en back-end......................................................... 11
Ilustración 19: representación de Fluid flexform configuration en back-end................................... 12
4. 1
1 Introducción
Esta 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 previos
Para 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 Framework
Se 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.
5. 2
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 Framework
Una 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 archivos
Esta 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: .typo3confextmiextension.
6. 3
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.php
Este 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.gif
Es el icono que se mostrara en la extensión.
5.2.3 ext_emconfig.php
Este archivo contiene información básica sobre la extensión: información sobre el autor,
compatibilidad y dependencia, entre otros parámetros.
Ilustración 3: estructura de carpetas y
archivos
7. 4
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.txt
Este archivo se encuentra en el fichero Configuration/Typoscript/ y es referenciado por el archivo
ext_tables.php.
8. 5
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.
9. 6
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 Viewhelper
El 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.
10. 7
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 Flexform
El 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:
11. 8
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
12. 9
Una vez que contamos con los diferentes archivos de la extensión configurados correctamente,
será posible instalar y probar la extensión.
6 Instalación de la extensión en TYPO3
En 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.
13. 10
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.
Ilustración 17: limpieza de caches
14. 11
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.
15. 12
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.