Testmaker: Uso mediante archivos de cuestionario

La aplicación genera cuestionarios a partir de la información contenida en archivos con formato YAML. YAML es un formato de serialización de datos -comúnmente utilizado en archivos de configuración-, que posee una estructura y sintaxis sencillas. A los archivos YAML utilizados por la aplicación los llamaremos archivos de cuestionario

Los elementos que forman un archivo de cuestionario son dos: conjuntos de ítems y elementos ítem. Los conjuntos de ítems se corresponden con las secciones que componen un cuestionario y están formados por elementos ítem. Los elementos ítem son cada una de las preguntas que se le presentan al participante.

Las propiedades de los elementos se especifican mediante el valor de sus atributos. Son atributos, entre otros, el título de un conjunto de ítems, el formato de respuesta a un ítem, las etiquetas de un conjunto de ítems con formato de respuesta likert, etc. (Los atributos permitidos para cada elemento se encuentran en Etiquetas de atributos)

Tanto los identificadores de los elementos como los atributos se declaran mediante etiquetas. Los elementos se identifican con un nombre asignado por el usuario (p. ej. "conjunto1" o "item1") y sus atributos se añaden en las líneas siguientes, manteniendo en cada uno de ellos un espacio de tabulación de separación respecto al identificador del elemento.

Lo anterior se entenderá mejor con un ejemplo:

conjunto1: 
[tab] titulo: "título del conjunto de ítems"
[tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título"
[tab] items:
[tab][tab][...]
 
* [tab] indica un espacio de tabulación

En el ejemplo se puede ver cómo tras crear un nuevo conjunto de ítems ("conjunto1"), los atributos de este conjunto mantienen un espacio de tabulación de separación respecto al identificador del conjunto ("conjunto1"). (La referencia completa de atributos se encuentra en Etiquetas de atributos)

Como puede observarse, cada espacio de tabulación en el ejemplo anterior ha sido sustituido por [tab]. En todos los ejemplos mostrados en este manual, para indicar un espacio de tabulación se utilizará la etiqueta [tab]. El ejemplo anterior debería quedar así en el archivo de cuestionario:

conjunto1: 
        titulo: "título del conjunto de ítems"
        descripcion: "descripción del conjunto de ítems. Se muestra bajo el título"
        items:

Los archivos de cuestionario pueden editarse desde cualquier editor de texto. Algunos editores de texto están adaptados al formato YAML y hacen más fácil su edición, aplicando colores a los atributos e identificadores y mostrando los márgenes de espaciado de cada elemento. Notepad++ es uno de esos editores.

Otro aspecto a tener en cuenta es que los identificadores de elementos y las etiquetas de atributos de cualquier elemento del archivo deben ir seguidos siempre de dos puntos (:). Los dos puntos sirven como delimitador a partir del cual se incluirán los atributos (si se trata de un identificador de elemento) o el valor de un atributo. Si el valor del atributo es un listado (p. ej., un listado opciones de respuesta), éste se incluirá bajo la etiqueta del atributo, y cada uno de sus valores deberán estar precedidos por un guión (-) y mantener un espacio de tabulación respecto a la etiqueta del atributo.

identificador: 
[tab]atributo:
[tab][tab]- 'elemento del listado 1' 
[tab][tab]- 'elemento del listado 2' 
[tab][tab]- 'elemento del listado 3'

* [tab] indica un espacio de tabulación

Si el valor del atributo no es un listado, se colocará a continuación de los dos puntos.

identificador: 
[tab] atributo: 'valor'

Nota: Es recomendable el uso de comillas simples (') o dobles (") cuando el valor del atributo es un texto de gran extensión o incluye caracteres especiales (p. ej., dos puntos [:] o guión [-]). En las etiquetas de atributos y en los identificadores de elementos sólo está permitido el uso de caracteres alfanuméricos sin tildes.

Todo ítem del cuestionario debe estar incluido dentro de un conjunto de ítems. Los conjuntos de ítems representan las secciones en las que se divide un cuestionario.

Para crear un conjunto de ítems, en primer lugar se debe especificar su nombre (identificador). Como todo elemento o atributo, el identificador irá seguido de dos puntos (:). A continuación, y tras un salto de línea, se incluirán los atributos del conjunto. El listado de atributos disponibles se encuentra en Etiquetas de atributos - Conjunto de ítems

conjunto1: 
[tab] titulo: "título del conjunto de ítems" 
[tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título" 
[tab] items: 
[tab][tab][...]

La etiqueta items de un conjunto de ítems establece el delimitador a partir del cual se incluirán los ítems del conjunto. Cada ítem se declara dejando un espacio de tabulación respecto a la etiqueta items.

conjunto1: 
[tab] titulo: "título del conjunto de ítems" 
[tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título" 
[tab] items: 
[tab][tab] item1: 
[tab][tab] item2: 
[tab][tab] item3: 

[...][...] ...

* [tab]: indica un espacio de tabulación

En el ejemplo, item1, item2 e item3 son los identificadores de los tres ítems del conjunto conjunto1 que hemos declarado anteriormente. Los identificadores de ítems se utilizan, en combinación con el identificador de conjunto, para el registro de resultados. La codificación se realiza a partir del identificador del conjunto más el identificador del ítem. Por ejemplo, la codificación del ítem item1 quedaría así: 'conjunto1_item1'. De este modo se facilita la visualización de resultados y dificulta la existencia de identificadores ambiguos o duplicados.

Bajo el identificador del ítem se añaden sus atributos. Los atributos de cada ítem (ver referencia en Etiquetas de atributos - Ítem) se especifican manteniendo un espacio de tabulación respecto al identificador del ítem.

conjunto1: 
[tab] titulo: "título del conjunto de ítems" 
[tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título" 
[tab] items: 
[tab][tab] item1: 
[tab][tab][tab] texto: "título del ítem" 
[tab][tab][tab] formato: abierta

[...][...][...] ...

Ver ejemplo generado

Un ítem también puede utilizarse como elemento padre de un subconjunto de ítems. Los subconjuntos son útiles tanto para el análisis posterior de los datos como para que los participantes puedan advertir la relación existente entre algunos ítems. Los ítems de un subconjunto se muestran de forma diferenciada al resto de ítems del cuestionario, aplicando una numeración supeditada al elemento padre y modificando algunos aspectos visuales como los márgenes y el tamaño del texto. Además, la codificación de estos ítems facilita la comprensión de la estructura del cuestionario.

Para crear un subconjunto basta con añadir, al mismo nivel que el resto de atributos, la etiqueta items. En un ítem que posee un subconjunto sólo puede especificarse el atributo texto. En este caso, la etiqueta texto será asignada al título del subconjunto (de forma similar a la etiqueta titulo de un conjunto).

conjunto1: 
[tab] titulo: "título del conjunto de ítems" 
[tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título" 
[tab] items: 
[tab][tab] item1: 
[tab][tab][tab] texto: "título del subconjunto" 
[tab][tab][tab] items: 
[tab][tab][tab][tab] item1_subconjunto: 
[tab][tab][tab][tab] item2_subconjunto:

Ver ejemplo El ejemplo fue generado a partir de este archivo: ejemplo_subconjunto1.yml

En los ítems de un subconjunto pueden definirse los mismos atributos que en un ítem perteneciente a un conjunto, y deben mantenerse las mismas restricciones respecto al espaciado. La codificación de los ítems de un subconjunto se realiza a partir de la combinación del id. del conjunto donde se encuentra el ítem padre, del id. del ítem padre y del id. del ítem del subconjunto. En el ejemplo anterior, 'item1_subconjunto' quedaría codificado de la siguiente forma: 'conjunto1_item1_item1_subconjunto'. '[conjunto]_[ítem padre]_[ítem del subconjunto]'

La longitud máxima permitida para la codificación de un ítem es 70 caracteres, contabilizando guiones. Se recomienda utilizar identificadores compuestos por un número reducido de caracteres.

Existe la posibilidad de adjuntar un ítem a otro. Los ítems adjuntos se pueden utilizar para que el participante proporcione información adicional (p.ej. en una respuesta del tipo 'otros (especificar)', ver ejemplo). Con la etiqueta item_adjunto, situada al mismo nivel que el resto de atributos del ítem, se define un espacio donde declarar los atributos del ítem adjunto. Pueden utilizarse los mismos atributos permitidos para los ítems convencionales, aunque sólo admite dos tipos de formato de respuesta: desplegable o abierta.

conjunto1: 
[tab] titulo: "título del conjunto de ítems" 
[tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título" 
[tab] items: 
[tab][tab] item1: 
[tab][tab][tab] texto: "Elige una opción" 
[tab][tab][tab] formato: unica 
[tab][tab][tab] respuestas: 
[tab][tab][tab][tab] - "Opción 1" 
[tab][tab][tab][tab] - "Opción 2" 
[tab][tab][tab][tab] - "Otra (especificar)" 
[tab][tab][tab] item_adjunto: 
[tab][tab][tab][tab] texto: "Especificar" 
[tab][tab][tab][tab] formato: abierta

Ver ejemplo

En el ejemplo anterior, el ítem adjunto permite que el participante especifique su respuesta a la opción "Otra (especificar)" mediante un ítem de respuesta abierta.

La codificación de los ítems adjuntos se realiza añadiendo la extensión "adjunto" al id. completo del ítem al que acompañan. En nuestro ejemplo, la codificación quedaría así: 'conjunto1_item1_adjunto'.

Además de los dos elementos principales (ítems y conjuntos de ítems), existe un elemento de configuración general del cuestionario. Este elemento se define mediante la etiqueta cuestionario y permite especificar el título, descripción, mensaje de agradecimiento y estado de publicación del cuestionario. (Ver Etiquetas de atributos - Cabecera de cuestionario). El elemento cuestionario es opcional y puede ser incluido en cualquier parte del archivo.

cuestionario: 
[tab] titulo: "El título del cuestionario" 
[tab] descripcion: "Mensaje para el participante, objetivo del estudio, instrucciones para completar el cuestionario, etc." 
[tab] agradecimiento: "Mensaje de agradecimiento" 
[tab] estado: desarrollo

El archivo de cuestionario debe guardarse en el directorio '/cuestionarios' de la aplicación, añadiendo la extensión .yml (p. ej., cuestionario_ejemplo.yml). Al cuestionario generado en html se accede mediante la dirección testmaker/index.php?cuestionario=nombre_archivo_cuestionario. Donde nombre_archivo_cuestionario es el nombre del archivo de cuestionario que previamente hemos guardado en el directorio '/cuestionarios' (sin incluir la extensión yml).

Por ejemplo, si nuestro archivo de cuestionario ha sido guardado con el nombre 'ejemplo1.yml' en el directorio '/cuestionarios', el resultado generado en html se encontrará en 'testmaker/index.php?cuestionario=ejemplo1'

Nota: la ruta de acceso al cuestionario puede variar dependiendo del lugar de instalación de la aplicación. En el ejemplo se supone que el usuario ha instalado la aplicación en el directorio raíz del servidor web y que no ha modificado el nombre del directorio.

Nota: el nombre de los archivos de cuestionario no puede contener espacios.

Un ejemplo, paso a paso, de cómo crear un archivo de cuestionario puede encontrarse aquí: Creando un cuestionario paso a paso

La etiqueta cuestionario permite definir el título, descripción, hoja de estilos a utilizar, mensaje de agradecimiento, estado de publicación del cuestionario y si se incluirá una página a modo de introducción. Es opcional y puede declararse en cualquier parte del archivo de cuestionario. Si este elemento no se encuentra en el archivo, se cargarán los valores predeterminados.

• titulo El título del cuestionario. Aparece en la parte superior de cada página del cuestionario. Valor predeterminado: "Cuestionario"
• descripcion Un mensaje que se muestra antes de comenzar el cuestionario y que puede ser utilizado para dar información al participante sobre el objetivo del estudio, instrucciones sobre la cumplimentación del cuestionario, etc. Valor predeterminado: ''.
• agradecimiento Mensaje de agradecimiento que se le presenta al participante tras completar el cuestionario. Valor predeterminado: "Gracias por colaborar"
• estilo
  • Uso: estilo: nombre_hoja_estilos.css
  • Un parámetro opcional que permite especificar la hoja de estilos (CSS) a utilizar en el cuestionario, la cual deberá encontrarse en el directorio /html. Valor predeterminado: styles.css
• estado
  • Opciones: publicado, desarrollo (predeterminado)
  • El estado de publicación del cuestionario. El estado 'publicado' le indica a la aplicación que debe mostrar una copia guardada (caché) del cuestionario, sin necesidad de realizar todo el proceso de carga desde el archivo. Esto disminuye el consumo de recursos de la aplicación, sobre todo si el cuestionario requiere acceso a base de datos, si está formado por un gran número de ítems o si el número de accesos al mismo es elevado. Si el estado actual es 'publicado', al modificar el archivo de cuestionario, los cambios no se reflejarán en el cuestionario generado. Para crear una nueva copia que incluya los cambios efectuados es necesario eliminar la copia anterior. Las copias guardadas de los cuestionarios se almacenan en el directorio '/cache' (nombre_cuestionario.html). Si no se incluye esta etiqueta, el valor por defecto será 'desarrollo'.
• intro
  • Opciones: s (sí), n (no) (predeterminado)
  • Página de introducción que se muestra antes de iniciar el cuestionario. En ella se incluyen el título, la descripción del cuestionario y el mensaje de agradecimiento.

    cuestionario: 
    [tab] titulo: "El título del cuestionario" 
    [tab] descripcion: "Mensaje para el participante, objetivo del estudio, instrucciones para completar el cuestionario, etc." 
    [tab] agradecimiento: "Mensaje de agradecimiento" 
    [tab] estado: desarrollo
    [tab] intro: s

• txt_enviar Texto del botón 'enviar cuestionario'.
• txt_iniciar Texto del botón 'inciar cuestionario'.
• txt_seleccionar Texto 'seleccionar' del listado de opciones desplegable.
• txt_continuar Texto del botón 'pasar a la siguiente página'.
• txt_validar Texto de validación de errores.

Ver ejemplo: cuestionario=ejemplo_cabecera_intro. Archivo de cuestionario: ejemplo_cabecera_intro.yml

• titulo El título del conjunto de ítems. Se puede utilizar para delimitar apartados en el cuestionario (p. ej., Datos personales)
• descripcion Un texto descriptivo que se muestra bajo el título.
• pagina_nueva
  • Opciones: s (sí), n (no).
  • Indica si el conjunto debe mostrarse en una página diferente, junto con los conjuntos siguientes (si los hubiera). Puede utilizarse para dividir un cuestionario en diferentes páginas. Ver ejemplo. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_paginacion.yml
• texto_ids
  • Opciones: s (sí), n (no). Predeterminada: n.
  • Genera el identificador de cada ítem a partir del valor de su atributo texto. El identificador generado estará formado por caracteres alfanuméricos sin tilde y '_' en sustitución de otros caracteres.
• imagen permite mostrar una imagen en la cabecera del conjunto, bajo el título y la descripción. El valor aceptado para este atributo es un nombre de archivo de imagen (junto con la extensión), el cual ha de encontrarse en el directorio /imagenes de la aplicación.
• etiquetas Este campo se utiliza exclusivamente para definir las etiquetas de un conjunto de ítems con formato de respuesta likert. Las etiquetas se muestran en la parte superior de la tabla de ítems. Existen diferentes formas de especificar las etiquetas que poseerá el conjunto:
  • Listado de etiquetas. Es posible especificar cada una de las etiquetas a mostrar. Para ello, se creará una lista con los valores de las etiquetas bajo la etiqueta etiquetas.

    [tab] etiquetas: 
    [tab][tab]- "Nunca" 
    [tab][tab]- "A veces" 
    [tab][tab]- "Frecuentemente" 
    [tab][tab]- "Siempre" 

    Ver ejemplo. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_listado_etiquetas.yml

  • Etiquetas numeradas. Con la etiqueta num bajo la etiqueta etiquetas se especifica el número de etiquetas a mostrar. Las etiquetas se crearán de forma consecutiva desde '1' hasta el valor de num. El siguiente ejemplo crea etiquetas numeradas desde el 1 hasta el 4.

    [tab] etiquetas: 
    [tab][tab] num: 4
     
    [1] [2] [3] [4] 

    Ver ejemplo. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_etiquetas_numeradas.yml

  • Etiquetas numeradas con texto en los valores mínimo y máximo. Muestra un texto sobre el valor mínimo y máximo de la secuencia numerada. El texto para el valor mínimo se declara con la etiqueta min y para el valor máximo con la etiqueta max.

    [tab] etiquetas: 
    [tab][tab] num: 4 
    [tab][tab] min: Nunca 
    [tab][tab] max: Siempre 
    
    [Nunca] [Siempre] 
    [1] [2] [3] [4]

    Ver ejemplo. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_etiquetas_numeradas_minymax.yml

• items Bajo la etiqueta items y estableciendo un espacio de tabulación respecto a ésta, se definen cada uno de los ítems del conjunto.

  conjunto1: 
  [tab] titulo: "título del conjunto de ítems" 
  [tab] descripcion: "descripción del conjunto de ítems. Se muestra bajo el título" 
  [tab] items: 
  [tab][tab][...]

• texto La pregunta o texto del ítem.
• formato Define el tipo de respuesta permitida para el ítem y la forma en la que ésta se mostrará.
  • Opciones: likert, abierta, abierta_amplia binaria, unica, desplegable, multiple, multiple_multilinea
  • likert: Selección única. Las opciones posibles se declaran como atributo del conjunto mediante la etiqueta 'etiquetas'.
  • abierta: Crea un campo de texto.
  • abierta_amplia: Genera un cuadro de texto para respuestas de gran extensión.
  • binaria: Selección única. Se presentan dos opciones. Por ejemplo, "Indica tu sexo: Hombre | Mujer".
  • unica: Selección única. Se presenta un listado de opciones de respuesta.
  • desplegable: Selección única. Las opciones se muestran en un elemento que se despliega al hacer click sobre él.
  • multiple: Selección múltiple. Se presenta un listado de opciones de respuesta.
  • multiple_multilinea: Selección múltiple. Se presenta un listado de opciones de respuesta en el que cada respuesta ocupa una línea diferente.
  • Ver ejemplo con diferentes formatos de respuesta. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_formatos_respuesta.yml
• obligatorio
  • Opciones: s (sí), n (no). Predeterminada: s
  • Indica si el ítem es de respuesta obligatoria. La comprobación se efectúa cuando el participante envía el cuestionario o cuando pasa a la siguiente página, e impide que el participante complete el envío. Se muestra un mensaje de error sobre el botón de pasar página/envío notificando que algunos ítems no han sido respondidos.
• respuestas Opciones de respuesta para los ítems de selección única y múltiple (excepto likert). Este campo es obligatorio para los ítems de respuesta única, desplegable, múltiple y múltiple multilínea. Las opciones de respuesta para el ítem pueden definirse de diferentes formas, de un modo similar a la especificación de etiquetas de un conjunto de ítems.
  • Listado de respuestas. Es posible especificar cada una de las opciones de respuesta. Para ello, se creará una lista de respuestas bajo la etiqueta 'respuestas'.

    situacion_laboral: 
    [tab] texto: "¿Cuál es tu situación laboral?" 
    [tab] formato: binaria 
    [tab] respuestas: 
    [tab][tab]- "Empleado" 
    [tab][tab]- "Desempleado"

    Ver ejemplo. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_listado_respuestas.yml

  • Al participante se le mostrarán las opciones de respuesta listadas bajo la etiqueta respuestas. El identificador de cada respuesta, es decir, el valor que se registra en la base de datos, es, por defecto, el texto de la opción de respuesta. Es muy recomendable asignar identificadores a las respuestas cuando su extensión en caracteres es superior a 50. Así, se facilita el posterior análisis de los datos y se evita una posible corrupción de los datos debida a la presencia de caracteres extraños en la cadena de texto. Ejemplo con identificadores:

     situacion_laboral: 
    [tab] texto: "¿Cuál es tu situación laboral?" 
    [tab] formato: binaria 
    [tab] respuestas: 
    [tab][tab] emp: "Empleado" 
    [tab][tab] desemp: "Desempleado"

    Los identificadores de opciones de respuesta se declaran como si fueran etiquetas de atributos. De este modo, la respuesta registrada para el ítem 'situacion_laboral' podrá tomar el valor 'emp' o 'desemp', aunque al participante se le mostrarán las opciones 'Empleado' y 'Desempleado'.

  • Secuencia de valores numéricos. Esta opción sólo está disponible para los ítems de respuesta desplegable. El valor inicial de la secuencia se define en la etiqueta min, y el valor final, en la etiqueta max.

    [tab] texto: "¿En el último mes, en cuántas ocasiones has ido al cine?" 
    [tab] formato: desplegable 
    [tab] respuestas: 
    [tab][tab] min: 0 
    [tab][tab] max: 30

    Ver ejemplo. El ejemplo fue generado mediante este archivo de cuestionario: ejemplo_listado_respuestas_desplegable.yml

  • Carga de respuestas desde una base de datos. Para recuperar las opciones de respuesta almacenadas en una base de datos, bajo la etiqueta respuestas se incluirá el valor 'bd' seguido de '.' y a continuación el nombre de la tabla donde se encuentran las opciones de respuesta del ítem. (ver Base de datos).

    departamento: 
    [tab][tab] texto: "Indique el departamento al que pertenece" 
    [tab][tab] formato: desplegable 
    [tab][tab] respuestas: 
    [tab][tab][tab] bd.departamento_opciones

    En el ejemplo, las opciones de respuesta para el ítem con identificador 'departamento' se encuentran en la tabla 'departamento_opciones' de la base de datos de respuestas especificada en el archivo de configuración ('/config.php'). Cada registro de la tabla de opciones de respuesta debe poseer un campo identificador ('id') y un valor de respuesta ('texto').

    [id] [texto] 
    admin Administración 
    dir Dirección
    mantenimiento Personal de mantenimiento 

    El campo texto es el texto que se le mostrará al participante en las opciones de respuesta del ítem. El campo id es el valor codificado que se envía junto con el identificador del ítem, es decir, es el valor que será registrado en la base de datos o archivo de texto de resultados.