Actions

Nuevo sistema de plantillas en LS3.x

From LimeSurvey Manual

This page is a translated version of the page New Template System in LS3.x and the translation is 50% complete.

Other languages:
English • ‎Nederlands • ‎español • ‎日本語

Contents

Introducción

En esta página aprenderá a:

  • Usar el nuevo sistema de temas de LimeSurvey 3.0.
  • Usar la herencia para administrar sus propios temas.
  • Agregar una imagen a su tema.
  • Administrar opciones del tema para sus encuestas y grupos de encuestas.

LimeSurvey 3 presenta un nuevo sistema de motor de temas completo, basado en Twig 1.29, Bootstrap, y que permite la herencia de temas y las opciones de temas. Elimina por completo el antiguo sistema de reemplazar palabras clave . Ahora, el 100% del HTML del frontend se puede personalizar. Por ejemplo, en el antiguo sistema de temas, había una palabra clave {EVALUACIONES} que fue reemplazada por evaluaciones en HTML en el momento de la ejecución. Un diseñador de temas no tenía forma de personalizar este HTML (aparte de usar JavaScript). Ahora, hay un archivo llamado evaluaciones.twig que contiene la lógica (escrita en Twig) para generar este HTML. En estas páginas, le daremos una explicación sobre cómo usar este nuevo motor de temas.

Help.png No detallaremos aquí cómo funciona Twig. Es una especie de PHP muy simplificado que ofrece un alto nivel de seguridad gracias al sistema "sandbox" (lo veremos con más detalle en la parte sobre el código de Theme Engine Core). Si ya conoce PHP, le será extremadamente fácil de dominar. Si no conoce PHP, igual le debería ser bastante fácil de aprender. Por favor, eche un vistazo a la documentación de Twig 1.X: https: //twig.symfony.com/

Edición usando la interfaz de administración

Lista de temas

En el panel de administración, ahora hay un cuadro para acceder a la lista de temas:

La lista de temas después de una nueva instalación de RC3


La lista se divide en 5 columnas:

  • Una vista previa del tema: es solo un archivo de imagen llamado "preview.png" en la raíz del tema.
  • El "título" del tema como está especificado en el manifiesto (config.xml en la raíz del tema).
  • La descripción del tema: una cadena establecida en su manifiesto.
  • El tipo de tema: tema principal (proporcionado con LimeSurvey), tema de usuario (agregado en el directorio de carga), tema XML (no cargado en la base de datos).
  • Extenciones: si el tema se extiende otro tema, su nombre se indicará aquí.
  • Algunos botones de acción:
    • Instalar: cargará el manifiesto de un tema para agregarlo a la base de datos y lo hará disponible para su selección en el nivel de la encuesta.
    • Desinstalar: eliminará las entradas de configuración de un tema en la base de datos.
    • Editor de temas: lo redirigirá al editor de temas.
    • Opción de tema: lo llevará a la configuración global de las opciones de tema.

Editor de temas

Help.png Esta documentación supone que ya sabe cómo usar el Editor de plantillas en la versión anterior de LS.


El Editor de plantillas se ha mantenido lo más parecido del original. Así que, cuando abra una plantilla principal, no podrá editarla. Ahora, en lugar de un botón de "copia", tiene un botón de "Extender".

Nuevo extender tema

Una descripción rápida del concepto de herencia de temas

En LS3, un tema ahora se puede heredar de otro tema, puede "extender" otro tema. Esto significa que el directorio de temas estará prácticamente vacío, solo contendrá los archivos (vistas, hojas de estilo, scripts, recursos, etc.) que difieran de los originales. Al hacerlo así, será fácil para usted crear un conjunto de temas para sus diferentes usuarios sin tener que mantener muchos temas diferentes. Por ejemplo: puede tener su propio tema personalizado y luego una versión para una empresa (con su logotipo, su estilo, quizás un enlace a su sitio web en el pie de página, etc.), otra versión para otra empresa, etc. Si actualiza el CSS o el diseño global de su tema personalizado, todos los temas que hereden de él se actualizarán automáticamente. Tenga en cuenta que la herencia es recursiva: un tema puede extender un tema que extiende otro, etc.

Help.png También significa que si extiende uno de los temas centrales de LimeSurvey, aún se beneficiará de sus actualizaciones.

Novedades en la interfaz de usuario

Para extender el tema Monocromo de LimeSurvey, vaya a la lista de Plantillas, haga clic en el botón "Editor de plantillas" del tema Monocromo. Luego, haga clic en "extender" y valide el nuevo nombre "extend_monochrome".

Si ahora va al directorio de carga (con su cliente de archivos/ftp), verá que se ha creado un nuevo directorio: upload/themes/extend_monochrome que contiene un archivo XML y algunos directorios, pero la mayoría de los directorios estarán vacíos. No tiene vistas ni CSS ni JS. Sin embargo, aún puede seleccionar este tema como uno normal de una encuesta y se verá exactamente como el tema monocromo.

El árbol de temas (directorio y archivos) justo después de su creación. Está prácticamente vacío
Help.png Los recursos (jpg, png, etc.) del tema original se copian al extender un tema. Esto se debe a que si copia un archivo CSS del tema original localmente, y si se refiere a esos archivos (como en la declaración de imagen de fondo), necesitará encontrar esas imágenes en la ruta del tema actual.

El editor de temas para el tema extend_monochrome se ve así:

Edición del tema extend_monochrome



No hay gran diferencia con el antiguo editor de temas. Hagamos una lista de los principales cambios:

  • La palabra clave heredada en la lista de archivos. Significa que el archivo no está presente en el directorio de temas y que se usará el archivo del tema original.
Inherited.jpg


  • El editor principal (ACE editor) muestra el contenido del archivo seleccionado. Los archivos no solo contienen HTML, CSS o JS, sino también declaraciones Twig. Esas declaraciones de Twig nos dan la posibilidad de llevar algo de lógica a las vistas de temas que se encontraban en el núcleo antes, y que ahora se pueden personalizar.
Algo de código twig, para la Lista de encuestas


  • Es por eso que ahora tiene más tipos de pantallazos disponibles en el selector desplegable del menú superior. Verá páginas como 'Lista de encuestas', 'Cargar', 'Guardar', 'Error', 'Registro', 'Evaluaciones', 'Imprimir respuestas' que no estaban disponibles antes, o que realmente no podía personalizar antes.
' Ahora, puede personalizar todas las pantallas


  • El enlace 'sugerencia' en la parte inferior de la lista de archivos le ofrece la forma Twig de agregar una imagen en su HTML.
Tip picture.png


  • El botón 'guardar cambios' se convirtió en el botón Copiar al tema local y guardar cambios
Copytolocal.png

Ejemplo rápido: agregar una imagen

El botón Copiar al tema local y guardar los cambios hará exactamente lo que dice: si edita algo dentro del archivo y luego hace clic en ese botón, copiará el archivo al tema que está editando, y guardará sus cambios.
Por ejemplo: haga clic en el archivo layout_global.twig, luego justo antes del contenido del bloque ({% block content%}) agregue el texto "PRUEBA" y haga clic en el botón. Puede ver que la etiqueta del archivo cambió de “heredado” a “local” y ahora el botón es un simple botón guardar cambios.

justo después de hacer clic en el botón


Si abre un explorador de archivos y va al directorio upload/themes/extend_monochrome/views/, verá que contiene solo un archivo, el archivo layout_global.twig y que la cadena "PRUEBA" está allí.

¡Ahora el archivo está presente en su tema



Ahora, en lugar de agregar un texto aleatorio, agregaremos una imagen. Si hace clic en el enlace de la sugerencia, le dirá:
Para usar una imagen en un archivo .twig: {{ image('./files/myfile.png', 'texto alternativo del archivo', {"class": "myclass"}) }}
Si ha leído la documentación de Twig (y debería haberlo hecho en este punto), sabe que {{ function( ) }} hará eco del resultado de una función en la pantalla. Aquí, la función es image( ).

Help.png Si tiene curiosidad por saber qué hace esta función, puede encontrarla en el código aquí (versión de RC3): /application/core/LS_Twig_Extension.php#L219-L237 función image( ) en RC3

Si no entiende el código: no se preocupe, no necesita saber cómo funciona, pero si, por qué usarlo y cómo usarlo.


Debe usar la función image( ) por dos razones:

  • La función de imagen recorre el tema para encontrar la imagen. Si el tema en el que está trabajando se extiende a otro tema, y si copia el archivo donde insertó la imagen localmente, pero esa imagen no se copia en el tema local, recorrerá el árbol de herencia del tema para encontrar dónde está esa imagen .
  • Utilizará el administrador de activos, por lo que mejorará el rendimiento de su tema. Consulte la documentación de Yii Asset Manager para obtener más información al respecto: http://www.yiiframework.com/wiki/148/understanding-assets/

Entonces, para agregar una imagen a su tema:

  • Simplemente cárguela como de costumbre con el cargador de archivos a la derecha y luego agréguela donde lo desee en cualquier archivo de twig:

{{ image('./files/myfile.png') }}

  • Si desea agregar un texto alternativo para su imagen (para lectores de pantalla y validación HTML), agregue:

{{ image('./files/myfile.png'), ‘mi texto alternativo’ }}

  • Si desea agregar un atributo de clase y agregarle una identificación:

{{ image('./files/myfile.png'), ‘mi texto alternativo’, {“class”: “a_nice_css_class”, “id”: “any_id”} }}

Algunas cosas en nuestra lista de tareas pendientes

  • Brinde a los usuarios la posibilidad de cargar un archivo de vista previa personalizado desde el editor en sí.
  • Agregue un botón para eliminar el archivo local y volver al declaración heredada.
  • Sólo copie la imagen utilizada en los archivos CSS (enumerándolos en el manifiesto como archivo para copiar).
  • Recuerde de qué tema se extiende el actual (si lo hay).

Opciones de plantilla

Otra novedad de LS3 es la página de opciones de tema. Como veremos más adelante, los creadores de temas pueden crear sus propias opciones e incluso su propia página de opciones de administrador. Aquí, veremos rápidamente cómo funciona la página de opciones de las Plantillas principales. Para acceder a las opciones de tema a nivel global: haga clic en "opciones de tema" en la lista de temas.

Opciones avanzadas

<translate>
Other languages:
English • ‎Nederlands • ‎español • ‎日本語

When you open the theme options tab, you can choose to edit either its simple options or its advanced options. “Advanced options” is just a naked form that gives you access to the main theme configuration fields from the database. To understand how it works, you should also read about the XML file and the creation of a theme from scratch. So, it’s rather complex and made for advanced users.

However, if you do wish to perform advanced settings editing, click on the advanced options tab


Advanced.png


  • Files css: The CSS files that should be added to the template;
  • Files js: The JS files that should be added to the template;
  • Files Print Css: The CSS files to load when printing a template;
  • Options: This field includes the options (and their value) that should be parsed to the template view;
  • CssFramework Name: The name of the CSS framework to load. For now, only Bootstrap or nothing;
  • Cssframework Css: You can replace the core bootstrap.css in this field by a different custom version of it;
  • Cssframework Js: The field core boostrap.js can be replaced from here by a different custom version of it;
  • Packages To Load: You can load from this setting some core asset packages from LimeSurvey.

You’ll notice an upload input at the top, which gives you the possibility to upload a file into the file directory of the theme. These parameters can be used to change the entire appearance of the theme.

Important.png
  Warning! : Don't touch the values unless you know what you're doing!
</translate>

Opciones simples

La página de opciones simples proviene de la propia plantilla. Se realiza a través de un archivo de twig y algunos javascript dentro del directorio /options del tema: https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Enlace roto)

Help.png Esta página puede ser completamente diferente de un tema a otro, y se recomienda encarecidamente a los proveedores de temas que creen su propia apariencia.
Options.png



La página de opciones simples simplemente completa las entradas de formulario de opciones avanzadas. Puede verlo activando o desactivando una configuración en la página simple, y vea cómo la entrada relacionada en el formulario avanzado se modifica en consecuencia. Por ejemplo, en las opciones simples de la Plantilla predeterminada, si cambia el tema de Bootswatch a "Oscuro" y luego hace clic en la pestaña de opciones avanzadas (incluso sin guardar) verá que el campo "Cssframework Css" cambió de

{"replace": [["css/bootstrap.css","css/flatly.css"]]}
a
{"replace": [["css/bootstrap.css","css/darkly.css"]]}

Aquí están las diferentes opciones simples para los temas principales:

  • Modo Ajax: ¿Debería cargar la página siguiente a través de ajax (más rápido) o mediante recarga de página (mejor para la depuración)
  • Imagen de fondo: si se establece en Sí, se cargará la imagen llamada pattern.png (será reemplazada por un selector de archivos en Master)
  • Contenedor de caja: si está configurado en No, las preguntas no se incluirán en un cuadro (por lo que puede usar matrices largas más grandes que el ancho de la pantalla)
  • Brandlogo: si se configura en no, el nombre de la encuesta se mostrará en la barra superior, de lo contrario, puede seleccionar una de las imágenes dentro del directorio de archivos para utilizarla como imagen de logotipo.
  • Cuerpo animado: si se establece en sí, puede elegir una de las animaciones para aplicar cuando se carga el cuerpo de la encuesta.
  • Pregunta animada: lo mismo con las preguntas.
  • Alertas animadas: lo mismo con las alertas.
  • Tema Bootstrap: aquí puede elegir un tema Bootstrap para cargar. Provenientes de Bootswatch https://bootswatch.com/3/

La biblioteca utilizada para animaciones es animate.css: https://daneden.github.io/animate.css/ Por supuesto, un proveedor de temas podría agregar su propia biblioteca de animación o ninguna biblioteca de animación.

Help.png Los temas monocromáticos usan el mismo tema de color de arranque que la interfaz de usuario de administrador. No están utilizando el sistema de reemplazo de framework css, sino que simplemente agregan un archivo CSS. Por lo tanto, ilustran otra forma de tratar temas personalizados para proveedores de temas.

Sistema de herencia

En la parte anterior, hemos visto que un tema puede extender otro tema. Una configuración de tema también puede heredar de otra configuración de tema. Significa que para un tema determinado, puede tener una configuración en

  • nivel global (el que acabamos de ver accesible desde la lista de temas).
  • a nivel de grupo de encuesta.
  • un último a nivel de encuesta.

Cada parámetro en un cierto nivel puede heredar del nivel superior: herencia del grupo de encuesta. Primero, veamos el nivel del grupo de encuesta.

A nivel de grupo de encuesta

De hecho, una de las otras grandes novedades de LS3 es el sistema de grupos de encuestas. Ahora puede crear diferentes grupos para organizar sus encuestas. Para acceder, vaya a la lista de encuestas y luego haga clic en la pestaña del grupo de encuestas:

Pestaña de grupos de encuestas


En esta lista, tiene dos botones de acción. Si el grupo está vacío, puede eliminarlo. De lo contrario, siempre puedes editarlo. Al hacer clic en el botón editar, llega a la página de configuración del Grupo de encuesta:

Edición del grupo de encuesta predeterminado


La tercera pestaña de esta página se llama "Opciones de plantilla para este grupo de encuesta". Si hace clic en él, verá la misma lista de temas que en la lista de temas, excepto que aquí solo está visible el botón de opción (solo se puede acceder al editor de temas desde la lista principal).
Ahora, si hace clic en la opción de Plantilla predeterminada, verá esto:

En el Grupo de encuesta, las Opciones de plantilla se heredan por defecto


  • Heredar todo significa que toda la configuración se heredará del nivel de configuración Global.
  • Si va a la página de opciones avanzadas, verá que todos los campos están configurados para heredar.
  • Si hace clic en "no" para "Heredar todo" en el opciones simples, nuevamente verá una página muy similar a la página de opciones global. La única diferencia es que para cada campo, puede establecerlo en sí, no o heredar; y cada selector desplegable tiene un valor heredar.
Cada configuración puede tener un valor heredado
Help.png Un grupo de encuesta puede ser hijo de otro grupo. En este caso, heredará de su padre.

A nivel de encuesta

Al editar una encuesta, en el menú de la barra izquierda, verá una nueva entrada "Opciones de plantilla". Le llevará a la página de opciones de la Plantilla seleccionada para la encuesta actual. Encontrará el mismo sistema de herencia que en el grupo de encuesta, pero esta vez, heredar significa que la configuración se heredará del Grupo de encuesta de la encuesta.

Opciones de plantilla a nivel de encuesta

Ejemplo práctico

Digamos que está utilizando un solo tema para diferentes empresas (A y B). Configura sus opciones favoritas a nivel global (por ejemplo: ajax activado, animar el cuerpo con una diapositiva, alertas con un pulso). Luego, crea un grupo de encuestas para cada compañía: un grupo de encuestas para la compañía A que alojará todas las encuestas para esta compañía, y un grupo de encuestas para la compañía B que alojará todas las encuestas para la compañía B. En este nivel, establecerá solo el logotipo y el fondo, y dejará que las otras opciones hereden. Por lo tanto, todas las encuestas del grupo A utilizarán el logotipo de la empresa A, y todas las encuestas del grupo B, el logotipo de la empresa B. Para una de las encuestas de la empresa A, puede utilizar un fondo diferente en relación con el tema de la encuesta: simplemente cambia el fondo en las opciones a nivel de encuesta. Si alguien en la compañía B le dice que la alerta de pulso es demasiado agresiva y que preferiría algo más suave como un desvanecimiento, simplemente cambie la animación de alerta en el nivel del Grupo de encuesta B y todas las encuestas de este grupo ahora usarán esta animación. Si la empresa A cambia su logotipo, puede cambiarlo al nivel del Grupo de encuesta A, y todas las encuestas de este grupo utilizarán el nuevo logotipo.

Esos ejemplos se basan en las opciones actuales del tema central. Pero, por supuesto, si eres un proveedor de temas, o si eres capaz de escribir un poco con Twig, puedes agregar tus propias opciones. Por ejemplo, podría agregar una opción "pie de página de información" donde podría agregar datos como el sitio web de la empresa o un número de teléfono para obtener ayuda. Luego, si la empresa A tiene diferentes departamentos, con diferentes números de teléfono, puede crear un subgrupo para cada departamento en el Grupo de encuesta A. Cada subgrupo tendrá su propio número de teléfono en estas opciones.

Preguntas frecuentes sobre la personalización del tema

Encontrarás aquí algunas respuestas a las preguntas que se hicieron en el foro y que podrían ayudarte a personalizar tu tema.

Personalizar CSS / JS: tratar con el administrador de activos ("¿por qué no se aplican mis cambios?")


Si está intentando actualizar el CSS/JS de un tema editando directamente el código con su editor favorito, podría sorprenderse de que sus cambios no se apliquen.


Desde 2.50, LS utiliza el administrador de activos de Yii:Documentación sobre los Assets de Yii

Mueve los archivos CSS/JS de un tema a un subdirectorio tmp/ con una cadena aleatoria (por ejemplo: "tmp/1ef64ml/"). Entonces, si realiza algún cambio en un archivo css/js y se lo indica al administrador de activos, los archivos se copian en un nuevo subdirectorio con un nuevo nombre para que la memoria caché del navegador del usuario se actualice y vean el nuevo css/js . De lo contrario, los usuarios tendrían que limpiar el caché de su navegador.


Aquí los enlaces CSS en el encabezado cuando el administrador de activos está activado:
Assets on vanilla.jpg
Como puede ver, todos se refieren a subdirectorios en tmp/


Aquí los enlaces CSS en el encabezado cuando el administrador de activos está desactivado:
Asset off.png
Como puede ver, apuntan a los archivos reales del tema.


Help.png Por supuesto, si el Administrador de activos no sabe que usted ha cambiado el archivo, el archivo antiguo del directorio tmp/ antiguo permanecerá sin cambios y sus cambios nunca se aplicarán.

Por lo tanto, cuando edita CSS/JS de un tema, tiene varias posibilidades:

  • Puede usar el Editor de temas LS: éste trata con el administrador de activos y usted no tiene que preocúpese por nada.
  • Puede activar el modo de depuración: se desactivará el administrador de activos, por lo que se invocan los archivos css/js reales de sus temas (pero luego, debe actualizar la memoria caché del navegador en cada carga)
  • Puede actualizar el caché de activos: desde Configuración global -> General -> Borrar caché de activos.

Clearassets-ls3 3.png

Help.png La mejor solución es usar el editor de temas para editar el CSS personalizado.


El uso del editor de temas lo ayudará a comprender la arquitectura del nuevo motor de temas. Además, si está personalizando fruity, tenga cuidado con la especificidad de CSS: la mayoría de las definiciones usan el selector ".fruity" (una de la clases del elemento del cuerpo)

Agregar fuentes personalizadas a mi tema

La manera fácil: usando Google Font CDN

Bootswatch Survey Theme usa Google Font CDN. Echemos un vistazo a cómo funciona: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");

De esta forma, la fuente Lato se carga a través de las reglas CSS: https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72

body {
  ...
 font-family: "Lato";
 ...
}

De esa manera usted puede usar cualquier fuente de Google en su tema personalizado. Por supuesto, debe eliminar el selector de fuente de las opciones de su tema. Elimine esas líneas en options.twig: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

Uso de fuentes de manera local

Por supuesto, usted también puede descargar los archivos de fuente y usarlos desde un servidor local en lugar de desde Google CDN (mejor para la privacidad). Para tener un ejemplo de cómo hacerlo, aquí está nuestra versión local de la fuente 'noto': https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css

@font-face {
  font-family: 'Noto Sans';
  font-weight: 300;
  font-style: normal;
  src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...

Puede usar una definición muy similar en su archivo css de tema y luego copiando el archivo NotoSans-Regular.ttf en la carpeta css/font-src/ del tema.

Luego, aplique esa fuente a su cuerpo (o cualquier otro elemento) como arriba, y elimine la opción predeterminada de selector de fuente.

Crear su propio selector de fuente en las opciones

Por ahora, usted no puede usar fácilmente el selector de fuente principal para agregar su propia fuente en las opciones. ¡Primero tenemos que dar la posibilidad al usuario final de cargar paquetes personalizados (vea el siguiente párrafo: Una mirada al Selector de Fuentes de Fruity)
Aquí cómo proceder:

  • Agregue dos fuentes (my_custom_font y my_custom_other_font) a su tema, usando CDN o servidor local.
  • Luego, en su archivo css, agregue dos nuevas clases:


.font-my_custom_font {
 font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
 font-family: 'my_custom_other_font';
}
  • En el archivo XML de su tema, agregue una opción de fuente (la predeterminada será my_custom_font):
    <options>
        ....
        <font>my_custom_font</font>
    </options>
  • en option.twig, agregue su selector de fuente agregando estas líneas (no probado por ahora, así que puede venir a quejarse al foro si no funcionan):
                
                <div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
                    <hr/>
                </div>
                <div class='row action_hide_on_inherit'>
                    <div class='col-sm-12'>
                        <div class='panel panel-default'>
                            <div class='panel-heading'>{{ "My custom fonts" | t }}</div>
                            <div class='panel-body'>
                                <div class='form-group row'>
                                    <label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
                                    <div class='col-sm-12'>
                                        <select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
                                        {% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
                                            {% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
                                        {% endif %}
                                       <optgroup  label="{{ "My Custom fonts" | t }}">
                                       <option class="font-my_custom_font"     value="custom_font"   data-font-package=""  >Custom</option>
                                      <option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package=""  >Other</option>
                                      </optgroup>
                                       
                                        </select>
                                    </div>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>
    


Ahora sus usuarios deberían poder elegir entre esas dos fuentes.

Una mirada al Selector de fuentes de Fruity

En el futuro, daremos la posibilidad al usuario final de cargar sus propios paquetes de activos, incluidos los paquetes de fuentes. Facilitará cualquier personalización de fuentes.
Para entender los paquetes de Yii:
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

Los paquetes LimeSurvey se definen en diferentes archivos. Los paquetes de fuentes se definen aquí: https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
Por ejemplo, el paquete de fuentes Noto se define aquí: https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53

    'font-noto' => array(
        'devBaseUrl' => 'assets/fonts/',
        'basePath' => 'fonts',
        'css' => array(
            'noto.css',
        ),
    ),


El archivo noto.css que contiene está aquí: https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
Observe la definición de la clase css ".font-noto" al final de la misma:

@font-face {
  font-family: 'Noto Sans';
  ...
}
...
.font-noto{
    font-family: 'Noto Sans';
}


Luego, en el Tema Vanilla, la fuente noto se usa agregando el paquete noto y definiendo la opción de fuente noto:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

        <packages>
             ....
            <add>font-noto</add>
        </packages>

https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58

    <options>
        ....
        <font>noto</font>
    </options>


Entonces, la fuente de la clase de cuerpo se define usando este valor: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76

<body class=" ...  font-{{  aSurveyInfo.options.font }} ... " ... >

Por supuesto, el archivo XML solo contiene los valores predeterminados para la configuración de su tema. Pero, de hecho, esos valores se definen y leen dentro de la base de datos (tabla "template_configuration" (Pregunta: "template_" de "theme_"?) Como cadenas json. El archivo option.js solo usa el valor del selector de fuente de la opción simple para cambiar el valor dentro de la pestaña avanzada: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

Entonces, cuando esté disponible la funcionalidad "cargar paquete de activos", será fácil agregar un script que escanee todos los paquetes de fuentes existentes para agregarlos en el selector.

Adding theme options to control positioning and display of survey elements

This tutorial will show how to add options to an extended theme to display survey elements in various locations. In this case, we will create theme options to show the survey title in two different locations.

Help.png For the sake of simplicity, we will base the tutorial on an extension of the "bootswatch" theme in LimeSurvey version 3.4.3.

Create a custom theme

  1. Extend the "bootswatch" theme as described above.
  2. Copy custom.css to the local theme as described above.

Create new theme options

  1. Copy the contents of /themes/survey/bootswatch/options/ to /upload/themes/survey/yourThemeName/options/.
  2. Open /upload/themes/survey/yourThemeName/options/options.twig in an editor and find "{# Bootstrap Bootswatch theme #}". Directly before its parent <div class='row'> element, add this:
    		{# Custom survey name in navbar #}
    		<div class='row'>
    			<div class='col-sm-12 col-md-6'>
    
    				<div class='form-group row'>
    					<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
    					<div class='col-sm-12'>
    						<div class="btn-group" data-toggle="buttons">
    							<label class="btn btn-default">
    								<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
    								Yes
    							</label>
    							<label class="btn btn-default">
    								<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
    								No
    							</label>
    						</div>
    					</div>
    				</div>
    			</div>
    		</div>
    		<div class='row'>
    			<hr/>
    		</div>
    
    		{# Custom survey name below progress bar #}
    		<div class='row'>
    			<div class='col-sm-12 col-md-6'>
    
    				<div class='form-group row'>
    					<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
    					<div class='col-sm-12'>
    						<div class="btn-group" data-toggle="buttons">
    							<label class="btn btn-default">
    								<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
    								Yes
    							</label>
    							<label class="btn btn-default">
    								<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
    								No
    							</label>
    						</div>
    					</div>
    				</div>
    			</div>
    		</div>
    		<div class='row'>
    			<hr/>
    		</div>
    
  3. Open /upload/themes/survey/yourThemeName/config.xml and add two items to the "options" block so it looks like this:
        <options>
            <ajaxmode>on</ajaxmode>
            ...
            <surveyname1>on</surveyname1>
            <surveyname2>on</surveyname2>
        </options>
    
  4. This should give you two new options in the Theme Options screen like this:
    Tutorial tp 1 1.png

Modifed view for Survey Title in the navbar

  1. Create a new directory /upload/themes/survey/yourThemeName/views/subviews/header/.
  2. Copy /themes/survey/vanilla/views/subviews/header/nav_bar.twig to that new directory.
  3. Open /themes/survey/vanilla/views/subviews/header/nav_bar.twig and find "{# Logo option #}". Under that, modify the IF statement for the logo/survey-name, so it looks like this:
    		{# Logo option #}
            {% if( aSurveyInfo.options.brandlogo == "on") %}
                <div class="{{ aSurveyInfo.class.navbarbrand }} logo-container"  {{ aSurveyInfo.attr.navbarbrand }}  >
                    {{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
                </div>
            {% endif %}
            {% if( aSurveyInfo.options.surveyname1 == "on") %}
                <div class="{{ aSurveyInfo.class.navbarbrand }}"  {{ aSurveyInfo.attr.navbarbrand }} >
                    {{ aSurveyInfo.name }}
                </div>
            {% endif %}
    
  4. Add something like this to /upload/themes/survey/yourThemeName/css/custom.css:
    .navbar-brand {
        line-height: 60px;
        font-size: 32px;
    }
    
  5. Toggle the "Survey name in navbar" theme option to "Yes"
  6. You should see this:
    Tutorial tp 1 2.png

Modifed view for Survey Title under progress bar

  1. Create a new directory /upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews.
  2. Copy /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig to that new directory.
  3. Open /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig and add an <h1> element for the survey name. So it looks like this:
    <div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>
     
        {# Custom survey name #}
        {% if( aSurveyInfo.options.surveyname2 == "on") %}
        	<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
        {% endif %}
     
        {# Group Name #}
        {{ include('./subviews/survey/group_subviews/group_name.twig') }}
     
        {# Group Description #}
        {{ include('./subviews/survey/group_subviews/group_desc.twig') }}
     
        {#
            PRESENT THE QUESTIONS
     
            This is the main part. It will render each question for this group
         #}
     
        <!-- PRESENT THE QUESTIONS -->
        {% for  aQuestion in aGroup.aQuestions %}
             {{ include('./subviews/survey/question_container.twig') }}
        {% endfor %}
     
        <!-- Hidden inputs -->
        {% if aGroup.show_last_group == true %}
            <input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
        {% endif %}
     
        {% if aGroup.show_last_answer == true %}
            <input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
        {% endif %}
    </div>
    
  4. Add something like this to /upload/themes/survey/yourThemeName/css/custom.css:
    .navbar-brand {
        line-height: 60ph1.custom-survey-name {
    	margin: 0;
    	text-align: center;
    }
    
  5. Toggle the "Survey name below progress bar" theme option to "Yes"
  6. You should see this:
    Tutorial tp 1 3.png

Downloads

Creating a theme from scratch

Documentation coming soon.

For now, just giving few tips.

theme structure

Files and directories

When you create a Theme from scratch, you don't need to respect the file/directory structure/css/js from Vanilla. The mandatory css/js is added by core (you can still remove it if needed)

The only files your theme must have are the layout files:

  • layout_global.twig : render the pages for survey taking
  • layout_survey_list.twig : render the survey list (if this theme is set as default)
  • layout_errors.twig : used to render errors that block survey rendering. ( wrong survey id, empty group in preview group, etc.)
  • layout_user_forms.twig: renders the user forms such as: token (survey participant), and register.
  • layout_print.twig : used to print the survey to pdf
  • layout_printanswers.twig: print the answers

The content of those files, the files they include or not, is entirely up to you. All the other files and directories that you find on Vanilla are purely optional, feel free to organize your code the way you want.

Help.png If you read the frontend rendering code, you'll see that those files names appear directly in it. That's why they are mandatory.

Eg: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462

Content

In Vanilla's layout_global.twig, you'll see we use a variable called "include_content" to decide what to show https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

                    {% set sViewContent =  './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
                    {% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}

aSurveyInfo.include_content tell you what action is currently going on: showing questions? showing submit result? showing clear all? etc As you can see, in vanilla, we create one file to include by action. So if you want to know the list of actions, just check the vanilla's directory views/subviews/content, and remove the "twig" extension : https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

  • clearall.twig
  • firstpage.twig
  • load.twig
  • mainrow.twig
  • main.twig
  • optin.twig
  • optout.twig
  • outerframe.twig
  • printanswers.twig
  • quotas.twig
  • register.twig
  • save.twig
  • submit_preview.twig
  • submit.twig
  • userforms.twig

If you already created a them for 2.x versions of LimeSurvey, you'll notice that most of them corresponds to the old pstpl files for limesurvey 2.x. Again, there is no obligation for you in your theme to create those files, with those names, in this directory. You could for example just add a giant switch in layout_global.twig with the wanted HTML for each action.

The manifest config.xml

The manifest of the theme contains the main informations about your theme. When you install a theme, the content of the manifest will be loaded in the database, in two different tables: template and template_configuration. So each time you modify the manifest of a theme, you must uninstall and reinstall it (or just reset it). Because this process is annoying while developing a theme you can force the direct usage of the XML file rather than the DB entries. To do so, in config.php turn on debug mode and 'force_xmlsettings_for_survey_rendering' to true.

The metadata section

Nothing complex: just the main infos about your theme. It will be pushed in the table templates_configuration

    <metadata>
        <name>the_name_of_your_theme</name>
        <title>The Title of your theme</title>
        <creationDate>16/10/2017</creationDate>
        <author>Your Name</author>
        <authorEmail>your@email.org</authorEmail>
        <authorUrl>http://www.yourwebsite.org</authorUrl>
        <copyright>Your Copyright </copyright>
        <license>Licence of your theme</license>
        <version>version of your theme</version>
        <apiVersion>3</apiVersion>
        <description>Description of your theme</description>
        <extends>parent_theme</extends>
    </metadata>


Few remarks:

  • name: will be used as a key in the db. So it must be unique, and it should not have any special chars (no spaces). Note that cases will not be taken in account
  • Title: will be used to display your theme name in the different lists. It can have special chars
  • description: will be used in the main list of survey theme. It can contains special chars, and even HTML code by using
  • extends: optional, it defines the parent themes. So if any file is not present in this theme (twig/js/css/jpg, etc) it will look for it in the parent theme


Help.png If you extended one of the the 3 core themes (Vanilla, Bootswatch, Fruity), you can change the "extends" value from one parent theme to the other. Of course, you'll have to reset the theme.



The files section

This one is an important one. It will be pushed in the table template_configuration, in the field files_css, files_js, files_print_css as json arrays.

Eg: the files section of the Material Premium Theme:

    <files>
        <css>
            <add>css/bootstrap-material-design.css</add>
            <add>css/ripples.min.css</add>
            <replace>css/ajaxify.css</replace>
            <replace>css/theme.css</replace>
            <replace>css/custom.css</replace>
            <remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
        </css>
        <js>
            <replace>scripts/theme.js</replace>
            <replace>scripts/ajaxify.js</replace>
            <add>scripts/material.js</add>
            <add>scripts/ripples.min.js</add>
            <replace>scripts/custom.js</replace>
        </js>
        <print_css>
            <add>css/print_theme.css</add>
        </print_css>
    </files>

All the CSS/JS files present in this section will be loaded at the launch of the survey (in ajax mode. If ajax mode is off, then of course all the files are reloaded at each page).


They will be added to a Yii Asset Packet based on the name of the theme. So when Asset Manager is on (debug mode being off), those files will be copied to the tmp directory with the rest of the theme (so you can use relative path in the CSS and JS to reach the image files). About the Asset manager in Yii: https://www.yiiframework.com/wiki/148/understanding-assets About packages in Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail


They will use the inheritance system. It means that if you add a CSS/JS file to a theme, but it's not present in the theme, then the engine will look into all the mother themes of this theme and will use the first one it finds. So if a user extends your theme via the theme editor, all those files will be inherited in his theme. The keywords refer to this inheritance system.


  • add : it will add the file to the theme, and to all its inherited theme
  • replace: it will replace the the file of its mother theme
  • remove: it will remove the file from any package, even the core package (since 3.14)
Help.png Remember you can set in config.php 'force_xmlsettings_for_survey_rendering' so configuration is read from XML instead of DB (no reset needed). This will make easier to test the modifications of the XML files, and will avoid you to uninstall/reinstall theme at each modification of the XML


Few remarks on those keywords:


Inheritance tips

As explained before, the "add" keyword can refer to a file being in one of the mother theme. So you can "add" a file in this section, and still not having this file in your theme, but in one of its parents theme. The engine will look into all its parent themes and will use the first one it finds. If it can't find the file, and debug mode is on in config, and js frontend debug mode is on in global setting, a message in console will warn you. Eg: if we add in a my_theme: <add>css/unexisting.css</add>, in the console we'll see:

 (¯`·._.·(¯`·._.· Theme Configuration Error  ·._.·´¯)·._.·´¯) 

Can't find file 'css/unexisting.css' defined in theme 'my_theme'

If the debug mode is off, then no error at all will be seen. The engine will just ignore the wrong add statements.


When to use add, when to use replace, when can I just leave it to the parent theme?

First: add and replace are the very same keyword. You can use the one or the other, the engine will just do the same. They are distinct for human readers, so they understand what was your intention.


You can't add a file with the same name as the mother theme: it will always replace it. eg: If you have a file called "my_mother_theme/foo.css" and you add a file called "foo.cs" in the daughter theme, only "daughter_theme/foo.css" will be added to the theme. If you want to keep "my_mother_theme/foo.css", just choose another name for "daughter_theme/foo.css", like "daughter_theme/bar.css". So the keyword "add" can be used as a "replace" keyword.


If you wonder why: this make much easier the automatic generation of inherited theme, copying the file section works out of the box (no need to rename "add" to "replace" when extending one the file).


To make it clear, let's take the Fruity example. Here its css file section:


        <css>
            <add>css/variations/sea_green.css</add>
            <replace>css/animate.css</replace>
            <replace>css/theme.css</replace>
            <replace>css/custom.css</replace>
        </css>


If you look to the custom.css file in fruity, it is exactly the same as the vanilla one. We could delete the custom.css file inside fruity, the one of vanilla would loaded. We could remove the statement <replace>custom.css</replace> from the Fruity manifest, the statement from vanilla will be used, and the vanilla custom.css would be loaded.


So why do we use the statement <replace>custom.css</replace> inside the fruity manifest? The answer is easy: because we want the end user to be able to extend the fruity theme, to modify the file in his local theme, and to load this modified file from his inherited theme. To understand, just extend fruity and have a look to the extended theme. THe extended theme doesn't even have the file custom.css. So the one of fruity will be used. But: if the user create this file in the extended theme (by clicking on "extend" in the theme editor), then this file will be loaded from his theme.


So in general: if you create a theme from scratch not extending any theme, just use the add statement to add your css/js files. Easy peasy. if you create a theme extending another theme, and you don't want the users to be able to extends the css/js file from the mother theme: don't use the add statement in your manifest. THe files will still be loaded from the mother theme configuration. if you create a theme extending another theme, and you want to replace a file from the mother theme: use the replace keyword (the add keyword will have the same result) if you create a theme extending another theme, if you don't replace a given file from css/js, but you want the users to be able to extend this file: then use the "replace" statement in your manifest for this file. Even if you don't replace the file, by using the keyword replace in the manifest: you allow the user to do it if he wants to do it.


Only this very last case needs a bit of mental gymnastic ot understand, all the other cases are trivial.


Help.png

You can also register CSS and JS files directly from the twig code. Those files will be loaded only when the twig file is asked. If you want the users to be able to inherit those JS/Css files from the theme editor, remember to use the functions Template:RegisterTemplateCssFile('my style.css') and Template:RegisterTemplateScript('my script.js'). If you don't use those functions, your theme may work, but inheritance on it will be broken. It is the same logic as the Template:Image('my picture.jpg') function

The remove keyword

The remove keyword is available only since 3.14. With this one, you can remove any css/file from any package, even the core ones. It is used in Material Premium Theme to remove the Awseome Bootstrap Checkbox's files:

<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>

so you should use the very same syntax as the package's file (eg: "awesome-bootstrap-checkbox.css" alone without it's folder path would not work). You'll find the complete list of core packages and their files in /application/config/packages.php and config/third_party.php. For example, for awesome-bootstrap-checkbox.css: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

        'css'=> array(
            'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
        ),


Another way to find the exact name to use in the remove tag is to turn asset manager on (turning debug mode off or setting 'use_asset_manager'=>true in the config). Then, the path to use will be the one just after the random directory in the tmp directory. For example, for awesome-bootstrap-checkbox.css:

<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />

Files you should not remove:

jquery-3.1.1.min.js : needed

jquery-migrate-3.0.0.min.js : needed

survey.js : needed

moment-with-locales.min.js : needed for date question type (and some other i think)

em_javascript.js : needed for all ExpressionScript javascript

The options section

This section is relative to the option of your theme. It will be used to feed the filed "options" of the table template_configuration as a json array.

Further information

Some notes

NOTE: if you edit the XML file of a theme, you must uninstall and reinstall the theme so it's taken into account.

NOTE: to avoid that, you can force the use to the XML rather than DB. In config.php turn debug mode on and uncommment:

'force_xmlsettings_for_survey_rendering' => true, // Uncomment if you want to force the use of the XML file rather than DB (for easy theme development)

Becareful: everything will be loaded from the XML (included options, etc)


NOTE: if you manually edit the CSS/JS files (without using the Theme Editor), and if debug mode is off, you can now force the asset to be flushed. In "Global Settings", "General tab", click the button "Clear assets cache".

NOTE: if you remove the section