Expression Manager

Tutorial de início rápido

Visão geral

Ao personalizar os seus inquéritos, normalmente precisa de uma forma de especificar o seguinte:

1. Navegação/Ramificação - permitir que as respostas de um participante alterem a ordem pela qual as perguntas são apresentadas
2. Personalização/Piping - como formular a pergunta (por exemplo, fazendo referência a respostas anteriores ou conjugando frases com base no número ou no género dos participantes), ou como gerar relatórios personalizados (como pontuações de avaliação ou recomendações personalizadas).
3. Validação - garantir que as respostas cumprem determinados critérios, como valores mínimos e máximos, ou correspondem a um padrão de entrada

O Expression Manager (EM) oferece uma forma intuitiva de especificar a lógica de cada uma destas funcionalidades. Quase tudo o que possa escrever como uma equação matemática padrão é uma expressão válida, mesmo que esteja a chamar funções. Atualmente, o EM dá acesso a 80 funções e pode ser facilmente alargado para suportar mais. Permite também aceder às suas variáveis através de nomes de variáveis legíveis (em vez de nomes SGQA).

As secções seguintes mostram os principais locais onde o Expression Manager é utilizado

Relevância (controlo da navegação/ramificação)

Alguns inquéritos utilizam a "lógica Goto", de modo que, se responder à Pergunta 1 com a opção C, salta para a Pergunta 5. Esta abordagem é muito limitadora, pois é difícil de validar e falha facilmente quando é necessário reordenar as perguntas. O EM utiliza uma equação de relevância booleana para especificar todas as condições em que uma pergunta pode ser válida. Se a pergunta for relevante, é apresentada; caso contrário, é Não Aplicável e o valor NULL é guardado na base de dados. Isto é semelhante ao que pode ser feito através do editor de condições, mas o EM permite especificar facilmente critérios muito mais complexos e poderosos (e permite utilizar o nome da variável em vez da nomenclatura SGQA).

Esta imagem mostra uma forma de rever a lógica de relevância de um inquérito. Calcula o Índice de Massa Corporal. A equação de relevância é apresentada entre parênteses retos logo a seguir ao nome da variável (que está a verde). Assim, a relevância de weight, weight_units, height e height_units é 1 em todos os casos, o que significa que estas perguntas são sempre apresentadas. No entanto, a relevância de BMI é {!is_empty(height) and !is_empty(weight)}, o que significa que o BMI só será calculado se o participante introduzir um valor tanto para height como para weight (evitando assim o risco de um erro de divisão por zero). Além disso, a pergunta Report só é apresentada se o participante responder às quatro perguntas principais (height, height_units, weight, weight_units).

A relevância é apresentada e pode ser editada nos seguintes locais:

Ver / editar a relevância ao nível da pergunta

Esta equação calcula o Índice de Massa Corporal (IMC). Só é apresentada se a pessoa introduzir primeiro a sua altura e o seu peso.

Este é o ecrã de edição da pergunta BMI.

Tenha em atenção que não utiliza chavetas ao introduzir uma Equação de relevância.

Ver / editar a relevância ao nível do grupo

Este é um exemplo de um inquérito de recenseamento. A primeira página pergunta quantas pessoas vivem consigo e guarda esse valor na variável "cohabs". Esta página só é apresentada se tiver mais do que um coabitante (por isso é apresentada para a segunda pessoa que coabita consigo) e apenas se tiver indicado a relação da Pessoa Um consigo (p1_rel).

Como pode ver, o grupo tem também critérios de relevância ao nível da pergunta, de modo que cada pergunta só aparece depois de ter respondido à pergunta anterior (por exemplo, {!is_empty(p1_sex)}). O EM combina por si a relevância do grupo e a relevância ao nível da pergunta. As perguntas de um grupo só são apresentadas se o grupo como um todo for relevante. Depois, só é apresentado o subconjunto de perguntas do grupo que são relevantes.

Eis o ecrã para editar a relevância ao nível do grupo para essa pergunta:

Tenha em atenção que não utiliza chavetas ao introduzir uma Equação de relevância.

Personalização/Piping

O EM permite fazer facilmente personalização condicional, simples e complexa, das suas perguntas. Por vezes basta uma substituição simples, como dizer: "Disse que comprou [Produto]. O que mais gostou nele?". Outras vezes precisa de uma substituição condicional como "[Sr./Sra.] [Apelido], estaria disposto(a) a responder ao nosso inquérito?". Neste caso, pretende utilizar Sr. ou Sra. consoante o género da pessoa. Noutras situações precisa de uma substituição ainda mais complexa (por exemplo, baseada num cálculo matemático). O EM suporta cada um destes tipos de personalização/piping.

Equações condicionais

O exemplo do Índice de Massa Corporal mostra a capacidade de calcular o IMC de uma pessoa, mesmo permitindo-lhe introduzir a altura e o peso em unidades métricas ou não métricas.

Aqui, weight_kg é {if(weight_units == 'kg', weight, weight * .453592)}. Esta função if() significa que, se o participante introduziu o peso em quilogramas, é utilizado esse valor; caso contrário, o valor introduzido (que estava em libras) é multiplicado por .453592 para o converter em quilogramas. A variável height_m utiliza uma abordagem semelhante para calcular a altura da pessoa em metros, mesmo que ela tenha introduzido a altura em polegadas.

O IMC calcula a fórmula do peso como {weight_kg / (height_m * height_m)}.

Por fim, o relatório adapta condicionalmente a mensagem para o participante, indicando-lhe o que introduziu. ("Disse que tem 2 metros de altura e pesa 70 kg.")

Embora não esteja bem visível na imagem acima, weight_status utiliza instruções if() aninhadas para classificar a pessoa desde abaixo do peso até obesidade grave. Pode ver a respetiva equação na vista Mostrar lógica.

Na janela de edição desta pergunta, pode ver duas coisas:

1. A personalização tem de colocar as expressões entre chavetas
2. As expressões podem ocupar várias linhas se, como neste caso, quiser facilitar a leitura da lógica condicional aninhada.

Perguntas, respostas e relatórios personalizados

Nota: a personalização dinâmica pode não funcionar se as opções de resposta forem disponibilizadas em caixas de seleção na mesma página da pergunta. Isto deve-se ao facto de a personalização inserir uma tag <span> que não é válida dentro das opções de seleção.

Este exemplo mostra o relatório do IMC.

Esta é a janela de edição da mesma pergunta.

Como pode ver, tudo o que está entre chavetas é tratado como uma expressão, pelo que tem o realce de sintaxe (codificado por cores) na imagem anterior. Se tiver algum erro de escrita (como nomes de variáveis ou funções mal escritos ou não definidos), o EM mostra um erro, como este, indicando que height_unit é um nome de variável não definido (na verdade é height_units) e que rnd() é uma função não definida (o nome correto da função é round()). Em ambos os casos, os erros são rodeados por uma caixa vermelha para facilitar a sua deteção e correção.

Também pode ver que é possível criar rapidamente relatórios complexos, como uma tabela de valores introduzidos ou conselhos personalizados.

Lembre-se de que toda a personalização tem de colocar as expressões entre chavetas, para que o LimeSurvey saiba quais as partes da pergunta que são texto livre e quais devem ser processadas pelo Expression Manager.

Validação

O EM controla o funcionamento da maioria das opções avançadas das perguntas. Estas controlam aspetos como o número mínimo/máximo de respostas; os valores individuais mínimos/máximos; os valores mínimos/máximos da soma; e a verificação de que os valores introduzidos correspondem a padrões de cadeias de caracteres especificados. Continua a introduzir essas opções avançadas da pergunta como habitualmente. No entanto, agora qualquer valor num desses campos é considerado uma expressão, pelo que pode ter critérios de mínimo/máximo com relações condicionais complexas com outras perguntas.

Em todos estes casos, uma vez que a opção avançada da pergunta é sempre considerada uma expressão, não se utilizam chavetas ao especificá-la.

As páginas de inquéritos de exemplo mostram muitos exemplos práticos de utilização de expressões para validações.

Introdução

O LimeSurvey utiliza o novo módulo Expression Manager (EM), que permite ao LimeSurvey suportar ramificações, avaliações, validações e personalização mais complexas. Substituirá a forma como o LimeSurvey gere as substituições, condições e avaliações no back-end. Também acelerará consideravelmente o processamento, uma vez que elimina a maioria das leituras da base de dados em tempo de execução. O EM foi desenvolvido pelo Dr. Thomas White (TMSWhite).

Esta página da wiki é a referência definitiva para a sintaxe e as funcionalidades do Expression Manager.

Definições principais

1. Expressão: Qualquer coisa entre chavetas
   • Desde que não haja espaço em branco imediatamente após a chaveta de abertura ou antes da chaveta de fecho
   • O conteúdo das expressões é avaliado pelo EM, pelo que pode conter fórmulas matemáticas, funções e processamento complexo de cadeias de caracteres e datas.
2. Personalização: Por vezes chamada "piping", é o processo de modificar texto de forma condicional
   • Tem acesso a todos os 'campos de substituição', aos dados do participante e aos dados das respostas.
   • Também tem acesso mais fácil às perguntas, às respostas e às respetivas propriedades.
3. Equação de relevância: Um novo atributo da pergunta que controla a visibilidade da pergunta
   • Se existir uma equação de relevância, a pergunta só é mostrada se a relevância for avaliada como verdadeira.
   • Internamente, todos os comandos array_filter e array_filter_exclude passam a ser relevância ao nível das perguntas secundárias
4. Tipo de pergunta Equação: Um novo tipo de pergunta que guarda cálculos ou relatórios na base de dados
   • É como uma pergunta Boilerplate, mas o seu conteúdo é guardado na base de dados mesmo que defina "Ocultar sempre esta pergunta"
5. Código da pergunta: Este é o nome de variável preferido para o EM
   • Pode ser um nome descritivo que indique o objetivo da pergunta, facilitando a leitura de lógica complexa
   • Os códigos de pergunta válidos NÃO devem começar com um número, por isso, ao utilizar o código da pergunta para numerar as suas perguntas, utilize simplesmente "q1", "q1a" ou "g1q2".
   • É o que atualmente se torna o nome da variável se exportar dados para SPSS ou R, pelo que, se faz análise estatística, provavelmente já o tornou único.

Tenho de utilizar o EM?

A resposta curta é não (mas também sim).

O EM é totalmente retrocompatível com os inquéritos existentes. Assim, se estiver satisfeito com a utilização de condições e avaliações ao estilo do LimeSurvey nas versões <= 1.91+, pode continuar a fazê-lo.

No entanto, o EM substitui por completo a forma como o LimeSurvey trata internamente as condições. Embora ainda possa utilizar o editor de condições para criar e gerir condições, o LimeSurvey 1.92 converte-as nas equações de relevância equivalentes. Como parte da atualização, o LimeSurvey 1.92 converte automaticamente todas as condições existentes em equações de relevância.

Isto deverá dar-lhe o melhor dos dois mundos: pode continuar a utilizar o LimeSurvey como está habituado, mas verá a equação de relevância equivalente, para poder migrar gradualmente para equações de relevância diretamente sempre que entender.

Posso misturar o uso de Condições e Relevância?

Sim. Pode utilizar o editor de condições para algumas perguntas e o editor de relevância para outras. As condições são convertidas automaticamente em relevância quando guarda a pergunta.

Note que partimos do princípio de que, se estiver a utilizar o editor de condições, pretende que essas condições substituam qualquer equação de relevância introduzida manualmente. Assim, se tiver condições existentes e quiser editar manualmente a relevância, elimine primeiro as condições dessa pergunta. Em concreto, copie a equação de relevância gerada para um editor de texto, utilize o menu de condições para eliminar todas as condições dessa pergunta (o que também eliminará a relevância), edite a pergunta e cole a equação de relevância gerada, a partir do editor de texto, no campo de relevância dessa pergunta (e guarde a pergunta). Se houver procura suficiente para eliminar condições sem eliminar a equação de relevância gerada, poderemos adicionar um processo de conversão em massa.

Como devo escolher entre Condições e Relevância?

Eis uma lista das vantagens e desvantagens de cada estilo:

Estilo	Vantagens	Desvantagens
Condições	1. Boa interface gráfica para criar condições simples 2. Interface gráfica bem documentada e conhecida da equipa de suporte	1. Só suporta comparações simples e não lida bem com condições AND/OR 2. As condições em cascata funcionam de forma irregular 3. Lento - utiliza intensivamente a base de dados, pelo que pode tornar mais lentos os inquéritos longos 4. Alguns problemas reportados ao recarregar condições 5. A interface gráfica não escala bem quando existem dezenas, centenas ou milhares de perguntas 6. Pode ser lento converter inquéritos em papel, pois é necessário utilizar nomes SGQA 7. Muitas vezes é necessário um programador para codificar à medida a lógica necessária para ramificações complexas
Relevância	1. Suporta lógica muito complexa, incluindo mais de 80 funções e operadores matemáticos/de cadeias de caracteres 2. Suporte perfeito para lógica em cascata 3. Rápido - sem chamadas adicionais à base de dados, pelo que suporta inquéritos com mais de 1000 perguntas 4. Sem problemas ao recarregar a lógica, pois não requer códigos SGQA 5. O realce de sintaxe escala para inquéritos com mais de 1000 perguntas 6. Fácil e rápido de utilizar por grupos que pretendam informatizar inquéritos existentes em papel. 7. Suporta facilmente entrevistas semiestruturadas e inquéritos epidemiológicos sem necessidade de programadores	1. Sem interface gráfica para condições simples - utilize antes o realce de sintaxe 2. É recente, pelo que as equipas de suporte ainda não dominam o EM.

Em suma, se estiver satisfeito com o funcionamento do LimeSurvey 1.91+, não há motivo para alterar a sua forma de trabalhar.

Quais são outras vantagens de utilizar o EM?

Eis outras razões pelas quais pode querer utilizar o EM.

1. Cálculos - pode criar qualquer cálculo que imagine:
   • Tem acesso a todos os operadores e funções matemáticas comuns
   • Tem acesso a mais de 70 funções matemáticas, de datas e de processamento de cadeias de caracteres
   • É relativamente fácil para os programadores adicionarem novas funções se os utilizadores precisarem delas
2. Guardar cálculos na base de dados
   • Agora pode calcular cálculos simples e complexos e/ou pontuações de escalas E guardá-los na base de dados sem necessidade de JavaScript.
   • Para isso, utiliza o tipo de pergunta Equação.
3. Avaliações
   • Agora pode criar avaliações ou pontuações de escalas a partir de qualquer tipo de pergunta, e não apenas do subconjunto que era suportado anteriormente
   • Pode utilizar a personalização para mostrar pontuações de avaliação parciais ou totais em qualquer local necessário - mesmo na mesma página
   • Tem mais controlo sobre os relatórios gerados com base nessas pontuações de avaliação
   • Pode guardar pontuações de avaliação na base de dados sem necessidade de JavaScript
   • Pode ocultar pontuações de avaliação sem necessidade de JavaScript ou CSS
4. Campos de substituição
   • Utilize o código da pergunta para inserir valores das respostas a perguntas anteriores - isto torna a leitura e a validação mais fáceis.
5. Personalização - pode mostrar texto condicionalmente com base noutros valores
   • Utilize o tratamento adequado para um participante, como (por ex. "Olá [Sr./Sra.] Silva")
   • Produza frases gramaticalmente corretas quando o singular/plural é relevante: (por ex. "Tem 1 filho" vs. "Tem 2 filhos")
   • Conjugue verbos e flexione nomes de forma adequada com base no género e no número do participante.
6. Novos atributos de variáveis - pode aceder aos seguintes para fazer a sua personalização:
   • (sem sufixo) - um alias para qcode.code
   • .code - o código de resposta selecionado para a pergunta, se esta for relevante (caso contrário, vazio), ou o valor de texto se não for uma pergunta com códigos
   • .NAOK - o mesmo que .code, mas pode fazer parte de cálculos ou listas mesmo que seja irrelevante
   • .value - o valor da avaliação para a pergunta, se esta for relevante (caso contrário, vazio), ou o valor de texto se não for uma pergunta com códigos -- disponível se as avaliações estiverem ativadas para o inquérito, caso contrário é sempre zero
   • .valueNAOK - o mesmo que .value, mas pode fazer parte de cálculos ou listas mesmo que seja irrelevante
   • .shown - a resposta tal como apresentada ao utilizador
   • .qid - o identificador da pergunta
   • .gid - o identificador do grupo de perguntas
   • .sgqa - o valor SGQA da pergunta
   • .jsName - o nome correto da variável JavaScript da pergunta, independentemente de estar definida nesta página ou noutra
   • .qseq - a sequência da pergunta (a começar em 0)
   • .gseq - a sequência do grupo de perguntas (a começar em 0)
   • .mandatory - se a pergunta é obrigatória (Y/N)
   • .question - o texto da pergunta
   • .relevance - a equação de relevância da pergunta
   • .grelevance - a equação de relevância do grupo de perguntas
   • .relevanceStatus - se a pergunta é ou não atualmente relevante (booleano (pode ser diferente em PHP e JS))
   • .type - o tipo de pergunta (o código de um caractere)
7. Alterações dinâmicas na página
   • Toda a relevância, cálculo e personalização funciona dinamicamente numa página - pelo que as alterações de valores atualizam instantaneamente a página
   • Assim, as perguntas aparecem/desaparecem dinamicamente consoante sejam relevantes
   • As perguntas também são personalizadas dinamicamente com base nas respostas na página, pelo que pode ver totais parciais, frases personalizadas e relatórios à medida.
8. Novo ecrã de entrada de dados
   • Além de utilizar o atual sistema de entrada de dados, pode simplesmente utilizar o Survey-All-In-One.
   • Este suporta a relevância e a personalização na página, pelo que os operadores de entrada de dados podem percorrer rapidamente os campos e só terão de introduzir as respostas relevantes
   • Isto pode ser crítico se a pessoa que introduz os dados precisar de ver a personalização, que também é dinâmica.
9. Elimina a necessidade da maior parte do JavaScript personalizado
   • O EM suporta facilmente cálculos complicados, pontuações, personalização e lógica condicional.
   • Algumas situações continuarão a precisar de JavaScript (como esquemas personalizados e ocultação condicional de subelementos de perguntas), mas o seu JavaScript pode utilizar as funções do EM para aceder às perguntas pelo respetivo Qcode em vez do SGQA, e aceder a qualquer uma das propriedades das perguntas acima listadas.

Quais são outras novas funcionalidades úteis possibilitadas pelo EM?

Quer continue a utilizar o editor de condições, quer escreva manualmente equações de relevância, obtém estes benefícios adicionais:

1. Pode criar critérios de validação mais complexos
   • Todos os atributos avançados da pergunta (como max_answers, min_num_value_n, max_num_value) podem utilizar expressões. Assim, os seus critérios de mínimo/máximo podem ser facilmente ajustados com base em respostas anteriores, mesmo que estejam na mesma página.
   • O EM também trata de toda a validação baseada em expressões regulares, pelo que pode combinar de forma robusta atributos de pergunta baseados em preg e em equações.
2. Reordenação (ou eliminação) fácil de perguntas e grupos
   • Antes da versão 1.92, não era possível reordenar perguntas ou grupos se o LimeSurvey considerasse que essa reordenação podia quebrar as condições em que eram utilizados. Da mesma forma, não era possível eliminar perguntas se outras perguntas dependessem delas.
   • Com o realce de sintaxe do EM, é fácil ver e validar se tenta utilizar perguntas antes de estas serem declaradas. Por isso, agora pode reordenar ou eliminar perguntas e grupos sempre que quiser. O EM atualizará todo o realce de sintaxe para lhe mostrar possíveis erros.
   • A vista de reordenação de perguntas foi melhorada para ajudar nesta revisão. Agora mostra a equação de relevância e a personalização da pergunta, para que possa ver imediatamente se alguma variável fica cor-de-rosa (o que significa que é utilizada antes de ser declarada).
3. O índice de navegação de perguntas/grupos está sempre disponível e correto
   • Antes da versão 1.92, estes índices não estavam disponíveis se existissem condições complexas
   • Com o EM, podemos garantir que estão corretos.
   • Os participantes podem até voltar a uma pergunta anterior, alterar a resposta e depois avançar (ou submeter)
     • Ao avançar, o EM volta a validar todas as perguntas/grupos intermédios.
     • Se alguma pergunta se tornar irrelevante, ficará NULL na base de dados, para que os seus dados sejam internamente consistentes
     • Se alguma pergunta se tornar relevante ou passar a falhar as regras de obrigatoriedade ou de validação, o EM pára nessa página e obriga o utilizador a responder a essas perguntas antes de seguir para o destino final.
4. Conversão automática de condições em relevância
   • Quando atualiza a base de dados, são geradas equações de relevância para todos os inquéritos existentes que tenham condições
   • Sempre que importa um inquérito, as equações de relevância são criadas conforme necessário
   • Sempre que adiciona, elimina ou modifica condições, o EM gera a equação de relevância adequada.
5. Realce de sintaxe conveniente
   • Quando o EM mostra a equação de relevância, mostra o Qcode, mesmo que tenha introduzido um código SGQA, pois assumimos que será mais fácil de ler.
   • Todas as variáveis são codificadas por cores para mostrar se foram declaradas antes ou depois da pergunta atual (ou antes ou depois do grupo atual). Isto permite-lhe detetar e corrigir rapidamente os casos em que tenta utilizar variáveis em equações de relevância (incluindo array_filter), de personalização ou de validação antes de as declarar.
   • Além disso, se passar o rato sobre a variável codificada por cores, verá os metadados mais importantes dessa pergunta. Estes incluem o n.º de sequência do grupo, o n.º de sequência da pergunta, o Qcode, o texto da pergunta e todas as opções de resposta disponíveis (se for um tipo de pergunta com opções de resposta enumeradas).
     • A lista de opções de resposta utiliza esta sintaxe: 'answers':{key:val, ... }.
     • key tem a sintaxe 'scale~code', onde scale é a escala de resposta (por exemplo, para escala dupla) e code é o código da resposta.
     • val tem a sintaxe 'value~shown', onde value é o valor da avaliação (se utilizar avaliações, caso contrário code) (por exemplo, Qcode.value) e shown é o valor de apresentação visto pelo participante (por exemplo, Qcode.shown)
     • Isto significa que muitos inquéritos podem utilizar cálculos sem necessitar do modo de avaliação. Se tiver opções de resposta enumeradas que sejam únicas, não decimais e não negativas, pode simplesmente fazer cálculos com os valores de Qcode.code.
6. Revisão fácil de toda a lógica e conteúdo do inquérito
   • Existe uma nova funcionalidade Mostrar lógica do inquérito que lhe permite ver tudo sobre o inquérito (ou grupo ou pergunta) numa única página.
   • Mostra os detalhes ao nível do grupo, da pergunta, da pergunta secundária e da resposta para o âmbito selecionado (inquérito, grupo ou pergunta)
   • Mostra também a relevância, a relevância ao nível da pergunta secundária (para array_filter e array_filter_exclude), a equação de validação gerada (para preg e quaisquer regras de validação como soma mínima/máxima ou número de valores mínimo/máximo) e todos os atributos da pergunta não vazios.
   • Tudo tem realce de sintaxe para que possa ver possíveis erros de sintaxe (como parênteses não equilibrados ou utilização de variáveis antes de serem declaradas)
   • O realce de sintaxe permite uma navegação e edição rápidas do inquérito.
     • Se clicar no nome de uma variável, abre-se uma janela (ou separador) do navegador que mostra essa pergunta e permite editá-la.
     • Se clicar no nome de um grupo, abre-se uma janela (ou separador) do navegador com a vista de reordenação do grupo, para que possa mover facilmente as perguntas.
     • Todos os atributos da pergunta também têm realce de sintaxe. Isto permite-lhe definir e ver expressões nas opções avançadas da pergunta (por exemplo, basear o máximo/mínimo do número/soma de valores numa expressão)
   • O autor do EM utilizou uma vista semelhante (um pouco mais limpa) para permitir que os seus colaboradores epidemiologistas e a Comissão de Ética validassem e autorizassem inquéritos com milhares de perguntas em entrevistas estruturadas altamente ramificadas e personalizadas

Primeiros passos

A melhor forma de começar a utilizar o EM é:

• Instalar a versão estável mais recente a partir de http://www.limesurvey.org/en/download
• Importar e explorar os inquéritos de exemplo.
• Explorar os casos de utilização e guias práticos e os exemplos passo a passo.
• Explorar a documentação do EM (esta página)
• Examinar o conjunto de testes do EM incluído
  • Em qualquer inquérito, em ferramentas, selecione a opção EM
  • Funções disponíveis lista as mais de 70 funções e a respetiva sintaxe
  • Testes unitários de expressões isoladas
    • mostra exemplos de utilização de todas as funções e operadores do EM, e os resultados em PHP e JavaScript
    • note que existem poucas funções que geram resultados diferentes nas versões PHP e JavaScript, pelo que esta página permite-lhe planear a lógica do EM em conformidade.

Que funcionalidades é que o Expression Manager expande/substitui? (LimeSurvey <= 1.91+)

Condições => Relevância

As condições controlavam que perguntas estavam visíveis. A sintaxe geral era SGQA operador Valor, como 111X2X3 == "Y". As condições podiam ser combinadas com AND ou OR, mas misturar AND e OR era difícil. As próprias condições eram guardadas numa tabela separada, e uma grande parte do código do LimeSurvey era dedicada à gestão de condições. Devido ao acesso intensivo à base de dados, o processamento de um grande número de condições podia causar problemas de desempenho notórios. Além disso, depois de atribuir condições a perguntas ou grupos, muitas vezes não era permitido reordená-los ou eliminá-los.

Avaliações => Equações e micropersonalização

As avaliações permitiam aos utilizadores criar pontuações de escala a partir de um conjunto de perguntas. No entanto, não podiam mudar dinamicamente na página atual e os seus valores não eram guardados na base de dados.

Substituições => Micropersonalização

Os utilizadores podiam personalizar algumas mensagens e perguntas com base em respostas anteriores. Por exemplo, uma pergunta podia ser {TOKEN:FIRSTNAME}, disse que {SPORT.shown} era o seu desporto favorito. No entanto, não era possível fazer personalização condicional (como dizer "Sr." ou "Sra." consoante o género da pessoa), nem conjugar verbos ou declinar substantivos sem JavaScript sofisticado. Os autores podiam criar inquéritos que pareciam personalizar perguntas, mas isso exigia perguntas separadas para cada permutação e condições complexas para decidir que perguntas apresentar.

Validação

As perguntas podiam ser validadas com expressões regulares, com valores mínimos/máximos, ou permitindo que uma resposta servisse de valor mínimo ou máximo. No entanto, as validações não podiam basear-se em cálculos de outras variáveis sem JavaScript sofisticado.

Equações

As equações não eram suportadas sem JavaScript sofisticado.

Tipo de pergunta Equação

As equações não podiam ser guardadas na base de dados (por exemplo, a pontuação final de uma avaliação) sem JavaScript sofisticado.

Como é que o Expression Manager irá substituir/expandir essas funcionalidades?

O Expression Manager é um novo módulo principal do LimeSurvey que facilita muito o suporte do tipo de funcionalidades complexas que antes exigiam JavaScript personalizado. Está também a substituir a forma como o LimeSurvey gere atualmente as condições e as avaliações.

Nova terminologia ao referir o Expression Manager (EM)

O EM "pensa" nas suas funcionalidades nos seguintes termos:

• Ramificação baseada em relevância - se uma pergunta for relevante, é apresentada; caso contrário, não (por exemplo, fica invisível e é marcada como NULL na base de dados). Existe um novo campo de relevância para todos os tipos de pergunta, e também para cada grupo (para que possa aplicar um conjunto de condições a um grupo inteiro sem ter de copiar a mesma condição para cada pergunta, e/ou combinar a lógica condicional ao nível do grupo e da pergunta).
• Personalização - Depois de saber que perguntas devem ser apresentadas, a personalização (por vezes chamada piping) especifica como a pergunta deve ser colocada. Isto permite suportar não só a substituição simples (como {TOKEN:FIRSTNAME}), mas também a conjugação de verbos e a declinação de substantivos com base no género ou no número dos seus participantes. Permite também alterar a mensagem que transmite a um participante consoante este tenha respondido (ou a forma como respondeu) a outras perguntas.
• Equações - O EM adiciona um novo tipo de pergunta chamado Equação, que guarda o resultado de uma expressão. Os resultados destas equações são calculados e escritos na base de dados, mesmo que os oculte na página. Assim, são úteis para cálculos de pontuação ocultos, navegação baseada em equações complexas, avaliações e relatórios que devem ser gerados e estar facilmente disponíveis na base de dados.

Relevância e relevância em cascata

Todos os tipos de pergunta têm agora uma opção de relevância que controla se a pergunta é apresentada. O EM processa cada uma das equações de relevância pela ordem em que devem aparecer no inquérito. Se a expressão for verdadeira (ou estiver em falta - para suportar inquéritos antigos), a pergunta será apresentada. Se não for relevante, a pergunta ficará oculta e o valor ficará NULL na base de dados. Se não existirem perguntas relevantes num grupo, o grupo inteiro será ignorado.

Além disso, se alguma das variáveis de uma expressão for irrelevante, a expressão é sempre avaliada como falsa. Isto permite a relevância em cascata, para que não tenha de escrever equações de relevância muito longas para cada pergunta.

Imagine que tem 5 perguntas, Q1-Q5, e que só quer mostrar a Q2 se a Q1 tiver sido respondida, a Q3 se a Q2 tiver sido respondida, etc. As equações de relevância poderiam ser:

Código da pergunta	Relevância	Pergunta
Q1	1	Qual é o seu nome?
Q2	Q1	{Q1}, que idade tem?
Q3	Q2	Então, tem {Q2} anos. É casado(a)?
Q4	Q3 == "Y"	{Q1}, há quanto tempo é casado(a)?
Q5	Q4	Quantos filhos tem, {Q1}?

Os cálculos de relevância também funcionam em JavaScript - por isso, poderia colocar todas as perguntas acima numa só página e continuaria a funcionar como esperado. De facto, o EM substitui totalmente a forma como o EM processa os formatos de inquérito por inquérito, por grupo ou por pergunta. Agora todos utilizam exatamente o mesmo motor de navegação, pelo que funcionam de forma idêntica, independentemente do estilo do inquérito.

Enquanto permanecer na mesma página, todos os dados que introduziu continuarão lá, apenas ocultos. Assim, se introduzir alguma informação, depois escolher uma opção que as torne irrelevantes e a seguir as tornar relevantes novamente, as suas respostas continuarão disponíveis. No entanto, assim que passar para uma página diferente, todas as respostas irrelevantes serão perdidas para preservar a integridade do conjunto de dados.

Relevância ao nível do grupo

O Expression Manager também suporta relevância ao nível do grupo. Isto facilita a implementação de ciclos. Suponha que pretende recolher informações sobre até 10 entidades (como produtos ou pessoas de um agregado familiar), em que primeiro determina quantas entidades necessitam de seguimento (por exemplo, perguntando quantas pessoas vivem no agregado familiar, ou pedindo que os participantes assinalem de que produtos gostam numa lista extensa). Depois de saber quantas entidades necessitam de seguimento, pode usar relevância ao nível do grupo como {count >= 1}, {count >=2}, ... {count >= 10} para cada um dos 10 grupos de perguntas de seguimento. Dentro de cada grupo, pode ter lógica condicional ao nível da pergunta (por exemplo, perguntas de seguimento específicas por género ou idade para cada pessoa). As equações de relevância ao nível da pergunta e do grupo são combinadas com AND para determinar quais devem ser apresentadas.

Personalização / Piping

Tudo o que estiver entre chavetas é agora tratado como uma expressão (com uma exceção descrita abaixo). As expressões têm acesso a todos os LimeReplacementFields, a todas as variáveis (através de vários alias), a todos os operadores de equações típicos (matemáticos, lógicos e de comparação) e a dezenas de funções (que funcionam dinamicamente até do lado do cliente).

Com estas equações, pode fazer coisas como:

1. Mostrar condicionalmente mensagens personalizadas aos participantes com base em respostas anteriores
2. Criar avaliações e mostrar os respetivos resultados (ou ramificar condicionalmente ou mostrar mensagens) com base nesses resultados, tudo isto sem utilizar o módulo de avaliações
3. Conjugar verbos e declinar substantivos em perguntas, respostas e relatórios.
4. Mostrar resumos das respostas antes da página "Mostrar as suas respostas" no final do inquérito

Equações

Existe um novo tipo de pergunta chamado Equação. É semelhante a uma pergunta Boilerplate, exceto que guarda na base de dados o valor do que é apresentado. Assim, se o texto da pergunta de Equação contiver um cálculo de avaliação, esse valor seria guardado na base de dados numa variável que pode ser apresentada nas estatísticas públicas ou privadas.

Isto resolve um pedido comum: guardar as pontuações de avaliação na base de dados.

Sintaxe

Tudo o que estiver contido entre chavetas é agora considerado uma expressão (com uma exceção: não pode haver espaços em branco no início nem no fim - isto é necessário para garantir que o Expression Manager não tenta processar JavaScript incorporado).

Note que as expressões podem ocupar várias linhas, desde que não haja espaços em branco depois da chaveta de abertura nem antes da chaveta de fecho. Isto é especialmente útil para instruções if() aninhadas como esta:

{if(is_empty(PFTotals),
 '',
 if(PFTotals >= -5 && PFTotals <= -4,
   'Very Soft',
   if(PFTotals >= -3 && PFTotals <= -2,
     'Soft',
     if(PFTotals == -1,
       'Somewhat Soft',
       if(PFTotals == 0,
         'Moderate',
         if(PFTotals == 1,
           'Somewhat Hard',
           if(PFTotals >= 2 && PFTotals <= 3,
             'Hard',
             if(PFTotals >= 4 && PFTotals <= 5,
               'Very Hard',
               ''
             )
           )
         )
       )
     )
   )
 )
)}

O Expression Manager suporta a seguinte sintaxe:

• Todos os operadores matemáticos padrão (por exemplo, +,-,*,/,!)
• Todos os operadores de comparação padrão (por exemplo, <,<=,==,!=,>,>=, mais estes equivalentes: lt,le,eq,ne,gt,ge)
• Parênteses (para poder agrupar subexpressões)
• Operadores condicionais (por exemplo, &&,| | e estes equivalentes: and,or)
• Cadeias de caracteres entre aspas simples e duplas (cada uma pode conter cadeias com o outro tipo de aspas)
• Operador vírgula (permite ter uma lista de expressões e devolver apenas o resultado final)
• Operador de atribuição (=)
• Variáveis predefinidas (para referir perguntas, atributos de perguntas e respostas) - por exemplo, todos os códigos SGQA
• Funções predefinidas (já existem mais de 70 e é fácil adicionar mais)

Operadores

A sintaxe do EM segue a precedência normal dos operadores:

Nível	Operador(es)	Descrição
1	()	parênteses para agrupar ou chamar funções
2	! - +	operadores unários: não, negação, mais unário
3	* /	multiplicação, divisão
4	+ -	adição, subtração
5	< <= > >= lt le gt ge	comparações relativas
6	== != eq ne	comparações de igualdade
7	and	AND lógico
8	or	OR lógico
9	=	operador de atribuição
10	,	operador vírgula

Aviso sobre o operador de adição (+)

Para manter a consistência entre JavaScript e PHP, o operador de adição (+) faz a soma se ambos os operandos forem numéricos, mas faz a concatenação se ambas as partes forem cadeias de caracteres não numéricas. No entanto, recomendamos utilizar a função join() para concatenação e a função sum() para adição, pois torna a sua intenção mais clara e evita resultados inesperados se estava à espera de cadeias de caracteres mas obteve números (ou vice-versa).

Aviso sobre a incompatibilidade entre número e cadeia de caracteres e a comparação alfabética

Ao comparar valores com comparações relativas ou de igualdade, preste atenção à incompatibilidade de tipos. Um valor introduzido pelo utilizador ou um código de resposta selecionado pode ser usado como número se for claramente um número. Se colocar um dos valores entre ", forçará a comparação como texto (comparação alfabética). Se pretende comparar numericamente, nunca coloque o número entre aspas, ".

Por exemplo, Q0.NAOK > "50" é verdadeiro se Q0.NAOK for uma pergunta numérica com o valor 9. Isto acontece porque o operador > assume uma comparação alfabética e não numérica.

Para garantir a comparação de valores inteiros, pode usar intval(Q0.NAOK) > 50, mas lembre-se de que, se Q0.NAOK não for um número (vazio ou uma cadeia de caracteres), então intval(Q0.NAOK) == 0. Para comparar valores de texto ("A" < "B"), use diretamente strcmp : strcmp(Q0.NAOK,"B") ou strcmp(Q0.NAOK,"A5").

Cuidado com o uso do operador de atribuição (=)

Note que deve evitar usar os operadores de atribuição, a menos que seja absolutamente necessário, pois podem causar efeitos secundários inesperados. Por exemplo, se alterar o valor de uma resposta anterior, a lógica de relevância em cascata e de validação entre essa pergunta e a pergunta atual não é recalculada, pelo que poderá acabar com dados internamente inconsistentes (por exemplo, perguntas que permanecem respondidas mas deveriam ter sido anuladas com NULL, ou perguntas que são ignoradas mas deveriam ter sido respondidas). Em geral, se pretende atribuir um valor a uma variável, deve criar uma pergunta do tipo Equação e usar uma expressão para definir o seu valor. No entanto, há algumas raras ocasiões em que este operador é realmente necessário, por isso disponibilizámo-lo.

Para o alertar sobre este operador, ele é apresentado a vermelho nas equações de sintaxe (para que não o confunda com "==").

Utilizar o operador de atribuição

As principais razões pelas quais pode querer usar a atribuição são:

• Precisa de definir o valor por defeito de uma pergunta que não aceita valores por defeito através de equação (como a lista de botões de opção, em que a interface permite escolher uma das opções de resposta, mas não permite introduzir uma equação). No entanto, tenha cuidado, pois o LimeSurvey não conseguirá validar se a sua equação gera uma das respostas permitidas para essa pergunta.
• Precisa de alterar forçosamente a resposta a uma pergunta anterior com base numa resposta posterior
• Precisa de uma quota complexa: usar uma pergunta de escolha única oculta para a quota e defini-la através de atribuição
• etc...

Pode usar todo o sistema do Expression Manager para este fim.

  A atribuição é feita apenas em PHP. Não atualiza quaisquer valores na mesma página, apenas quando o utilizador navega com seguinte, anterior, guardar ….

  Se não utilizar uma pergunta de equação para este fim: a atribuição é feita apenas depois de a lógica da página atual estar concluída. O método recomendado é usar sempre uma pergunta de equação.

Alguns exemplos:

• Definir a resposta a uma pergunta de texto curto em minúsculas : {QCODE=strtolower(QCODE.NAOK)}
• Definir uma resposta por defeito para uma pergunta do tipo tabela no início de um inquérito : {Q1_SQ1=((is_empty(Q1_SQ1.NAOK),"A99",Q1_SQ1.NAOK)}
• Definir uma resposta por defeito para uma pergunta do tipo tabela de textos no início de um inquérito : {Q1_SQY1_SQX1 = ((is_empty(Q1_SQY1_SQX1.NAOK),"Inserted answer", Q1_SQY1_SQX1.NAOK)}
• Definir uma resposta com condição : {QCODE=if(YesNo="Y","A1","")}

Segurança XSS

Com a proteção XSS ativada, algumas funcionalidades do Expression Manager não podem ser utilizadas :

• iniciar uma tag HTML numa expressão e terminá-la noutra expressão
• utilizar uma expressão complexa num URL.

Exemplo e solução alternativa

• {if( 1 ,"<strong>","")}information{if( 1 ,"</strong>","")} não funciona com a segurança XSS; neste caso, pode utilizar {if(1,"<strong>information</strong>","information")}
• <a href="/script.php?value={if(QCODE == "Y","yes","no")}">next</a>, neste caso pode utilizar uma pergunta de equação, porque utilizar um código de pergunta completo é permitido : <a href="/script.php?value={EQUATION.NAOK}">next</a>

Acesso a variáveis

O Expression Manager fornece acesso apenas de leitura a todas as variáveis de que possa necessitar. Para compatibilidade com versões anteriores, fornece acesso ao seguinte:

• TOKEN:xxx - o valor de um código (TOKEN) (p. ex. TOKEN:FIRSTNAME, TOKEN:ATTRIBUTE_5) (apenas para inquéritos NÃO anónimos).
• QCODE.shown - o valor apresentado de uma resposta (p. ex. "Sim") através do Expression Manager.
• Todos os valores {XXX} utilizados pelos temas.
• No texto da pergunta, pode utilizar {QID}, substituído pelo identificador da pergunta, e {SGQ}, substituído pelo SGQA da pergunta

Além disso, o Expression Manager permite referir variáveis através do código da pergunta (a coluna 'title' da tabela de perguntas na base de dados). Este é também o rótulo da variável utilizado quando exporta os dados para SPSS, R ou SAS. Por exemplo, se tiver perguntas sobre nome, idade e sexo, pode chamar a essas variáveis name, age e gender em vez de 12345X13X22, 12345X13X23 e 12345X13X24. Isto torna as equações mais fáceis de ler e de validar por todos, além de permitir reordenar as perguntas sem ter de acompanhar os números dos grupos ou das perguntas.

Importante: Só é seguro referir variáveis que ocorrem em páginas ou perguntas anteriores.

Além disso, o Expression Manager permite aceder a várias propriedades da pergunta:

Sintaxe	Significado	Exemplo	Resultado do exemplo
Qcode	um alias de Qcode.code	{implode(',',name,gender)}	'Tom','M'
Qcode.code	o código de resposta selecionado para a pergunta, se esta for relevante (caso contrário, em branco), ou o valor de texto, se não for uma pergunta com códigos	{implode(',',name.code,gender.code)}	'Tom','M'
Qcode.NAOK	igual a Qcode - veja a discussão sobre NAOK	{gender.NAOK}	'M'
Qcode.value	o valor da avaliação da pergunta, se esta for relevante (caso contrário, em branco), ou o valor de texto, se não for uma pergunta com códigos	{gender.value}	'1'
Qcode.valueNAOK	igual a Qcode.value - veja a discussão sobre NAOK	{gender.valueNAOK}	'1'
Qcode.shown	o valor apresentado da pergunta	{implode(',',name.shown,gender.shown)}	'Tom','Male'
Qcode.question	o texto da pergunta	{gender.question}	'What is your gender?'
Qcode.mandatory	se a pergunta é obrigatória (Y/N)	{gender.mandatory}	'N'
Qcode.qid	o número interno da pergunta (não o número sequencial)	{gender.qid}	337
Qcode.type	o tipo de pergunta	{gender.type}	'G'
Qcode.jsName	o nome JavaScript correto da pergunta, independentemente de ser declarada nesta página ou noutra	{gender.jsName}	'java1827X3X337'
Qcode.gid	o número interno do grupo (não o número sequencial)	{gender.gid}	3
Qcode.qseq	o número sequencial da pergunta, começando em 0	{gender.qseq}	5
Qcode.gseq	o número sequencial do grupo, começando em 0	{gender.gseq}	1
Qcode.relevanceStatus	se a pergunta é atualmente relevante (0 ou 1)	{gender.relevanceStatus}	1
Qcode.relevance	a equação de relevância ao nível da pergunta	{gender.relevance}	'!is_empty(name)'
Qcode.grelevance	a equação de relevância ao nível do grupo	{gender.grelevance}	'num_children >= 5'
Qcode.sgqa	o valor SGQA desta pergunta	{gender.sgqa}	'1827X3X337'

Problema com o editor HTML

  Este problema foi corrigido após a versão 2.05 build 140803

Se utilizar o Editor HTML, alguns caracteres são substituídos por entidades HTML.

• & por &amp;
• < por &lt;
• > por &gt;

Se utilizar o Editor HTML, tem de utilizar :

• and para &
• lt para <
• le para <=
• gt para >
• ge para >=

Nomenclatura das variáveis Qcode

Eis os detalhes de como construir um Qcode (e aceder a algumas propriedades) por tipo de pergunta. Em geral, os Qcodes são construídos assim:

 QuestionCode . '_' . SubQuestionCode . '_' . ScaleId

O código da pergunta secundária e o identificador da escala têm de ser utilizados ou não, consoante o tipo de pergunta - veja a tabela abaixo. Para comment e other, os códigos das perguntas são QuestionCode_comment e QuestionCode_other

Tipo	Descrição	Código	Perguntas secundárias	Opções de resposta	Escalas	Código da resposta	Resposta apresentada	Relevância
5	Escolher entre 5 Pontos (botões de opção)	Q1		1-5		{Q1}	{Q1.shown}	{Q1==3}
B	Matriz (Escolher entre 10 Pontos) (botões de opção)	Q2	L1-L6	1-10		{Q2_L2}	{Q2_L2.shown}	{Q2_L2==7}
A	Matriz (Escolher entre 5 Pontos) (botões de opção)	Q3	1-5	1-5		{Q3_1}	{Q3_1.shown}	{Q3_1>=3}
1	Matriz (etiquetas flexíveis) de escala dupla	Q4	sq1-sq5	0:a1-a3	1:b1-b3	{Q4_sq1_0}	{Q4_sq1_1.shown}	{Q4_sq1_1=='b2'}
H	Matriz (flexível) - formato em coluna	Q5	1-5	s,m,t		{Q5_1}	{Q5_1.shown}	{Q5_1=='s'}
F	Matriz (flexível) - formato em linha	Q6	F1-F5	1-5		{Q6_F3}	{Q6_F3.shown}	{Q6_F3==4}
E	Matriz (Aumentar/Manter/Reduzir) (botões de opção)	Q7	1-7	I,S,D		{Q7_4}	{Q7_4.shown}	{Q7_4=='D'}
:	Matriz (múltipla flexível) de 1 a 10	Q8	ls1,todo,ls2	min,max,avg		{Q8_ls1_max}	{Q8_ls2_avg.shown}	{Q8_ls2_min==7}
;	Matriz (múltipla flexível) de texto	Q9	hp,st,sw	1st,2nd,3rd		{Q9_hp_3rd}	{Q9_hp_3rd.shown}	{Q9_hp_3rd=='Peter'}
C	Matriz (Sim/Incerto/Não) (botões de opção)	Q10	1-5	Y,N,U		{Q10_1}	{Q10_1.shown}	{Q10_3=='Y'}
X	Pergunta de texto fixo (boilerplate)	Q11					{Q11.shown}
D	Data	Q12				{Q12}	{Q12.shown}
*	Equação	Q13				{Q13}	{Q13.shown}	{Q13>5}
~124~	Submissão de ficheiro (regista o número de ficheiros carregados)	Q14				{Q14}		{Q14>0}
G	Lista de seleção (Drop-down) de sexo	Q15		M,F		{Q15}	{Q15.shown}	{Q15=='M'}
U	Texto livre muito longo	Q16				{Q16}	{Q16.shown}	{strlen(Q16)>100}
I	Pergunta de idioma	Q17				{Q17}	{Q17.shown}	{Q17=='en'}
!	Lista - Lista de seleção (Drop-down)	Q18		1-5		{Q18}	{Q18.shown}	{Q18==3}
L	Lista de seleção (Drop-down) / lista de botões de opção	Q19		A-Z		{Q19}	{Q19.shown}	{Q19=='X'}
O	Lista com comentário - lista de seleção (Drop-down) / lista de botões de opção + área de texto	Q20		A-F		{Q20},{Q20comment}	{Q20.shown}	{Q20=='B'}
T	Texto livre longo	Q21				{Q21}	{Q21.shown}	{strstr(Q21,'hello')>0}
M	Escolha múltipla (caixas de seleção)	Q22	A-F, other			{Q22_E}, {Q22_other}	{Q22_E.shown}, {Q22_other.shown}	{Q22_E=='Y'}
P	Escolha múltipla com comentários (caixa de seleção + texto)	Q23	A-F			{Q23_D}, {Q23_Dcomment}	{Q23_D.shown}	{!is_empty(Q23)}
K	Pergunta numérica múltipla	Q24	self,mom,dad			{Q24_self}	{Q24_self.shown}	{Q24_self>30}
Q	Textos curtos múltiplos	Q25	A-F			{Q25_B}	{Q25_B.shown}	{substr(Q25_B,1,1)=='Q'}
N	Pergunta do tipo numérico	Q26				{Q26}	{Q26.shown}	{Q26 > 30}
R	Estilo de classificação (ranking)	Q27	1-4			{Q27_1}	{Q27_1.shown}	{Q27_1==3}
S	Texto livre curto	Q28				{Q28}	{Q28.shown}	{Q28=='mine'}
Y	Sim/Não (botões de opção)	Q29				{Q29}	{Q29.shown}	{Q29=='Y'}

As variáveis reservadas 'this', 'self' e 'that'

Muitas vezes, pretende avaliar todas as partes de uma pergunta, como contar quantas perguntas secundárias foram respondidas ou somar as pontuações. Noutras ocasiões, pretende processar apenas determinadas linhas ou colunas de uma pergunta (por exemplo, obter as somas das linhas ou colunas e guardá-las na base de dados). Estas variáveis reservadas tornam esse processo relativamente simples.

A variável 'this' é utilizada exclusivamente nas opções avançadas de pergunta "Validação da equação da pergunta" e "Validação da equação da pergunta secundária". Expande-se para os nomes das variáveis de cada uma das células dessas perguntas. Assim, se quiser garantir que cada entrada é maior do que três, defina a "Validação da equação da pergunta secundária" como (this > 3).

As variáveis 'self' e 'that' são mais poderosas e funcionam como macros que são expandidas antes do processamento das equações. As opções de sintaxe são:

• self
• self.suffix
• self.sub-selector
• self.sub-selector.suffix

suffix é qualquer um dos sufixos normais de qcode (p. ex. NAOK, value, shown)

sub-selector é um dos seguintes:

• comments - apenas as perguntas secundárias que são comentários (p. ex., de escolha múltipla com comentários e de lista com comentário)
• nocomments - apenas as perguntas secundárias que não são comentários
• sq_X - em que X é um identificador de linha ou coluna. Apenas são selecionadas as perguntas secundárias que correspondem ao padrão X. Tenha em conta que a pesquisa é feita no identificador de código completo, pelo que sq_X corresponde e inclui as perguntas secundárias nX, X, Xn (p. ex., se utilizar sq_1, as perguntas secundárias a1, 1a, 1, 11 ou 001 são incluídas). Tenha atenção ao tipo de pergunta de escala dupla, em que os códigos das perguntas secundárias são QCODE_SQCODE_1 e QCODE_SQCODE_1, e ao tipo de pergunta de classificação (ranking), em que os códigos das perguntas secundárias são QCODE_1, QCODE_2 ....
• nosq_X - em que X é um identificador de linha ou coluna. Apenas são selecionadas as perguntas secundárias que não correspondem ao padrão X. Tenha em conta que a pesquisa é feita no identificador de código completo, pelo que nosq_X corresponde e não inclui as perguntas secundárias nX, X, Xn

Exemplos:

• Foi respondida alguma parte de uma pergunta? {count(self.NAOK)>0}
• Qual é a pontuação da avaliação desta pergunta? {sum(self.value)}

Também pode utilizá-las para obter totais de linhas e colunas. Imagine que tem uma matriz de números com as linhas A-E e as colunas 1-5.

• Qual é o total final? {sum(self.NAOK)}
• Qual é o total da linha B? {sum(self.sq_B.NAOK)}
• Qual é o total da coluna 3? {sum(self.sq_3.NAOK)}

A variável 'that' é semelhante à variável 'self', mas permite referir outras perguntas. A sua sintaxe é:

• that.qname
• that.qname.suffix
• that.qname.sub-selector
• that.qname.sub-selector.suffix

qname é o nome da pergunta sem quaisquer extensões de pergunta secundária. Assim, se criar uma pergunta 'q1', esse é o seu qname

Exemplos:

• Foi respondida alguma parte da pergunta q1? {count(that.q1.NAOK)>0}
• Qual é a pontuação da avaliação de q2? {sum(that.q2.NAOK)}
• Qual é o total final de q3? {sum(that.q3.NAOK)}
• Qual é o total da linha C em q4? {sum(that.q4.sq_C.NAOK)}
• Qual é o total da coluna 2 em q4? {sum(that.q4.sq_2.NAOK)}

As variáveis 'self' e 'that' podem ser utilizadas em qualquer relevância, validação ou personalização (tailoring).

A única ressalva é que, quando utiliza a funcionalidade Mostrar ficheiro de lógica, esta apresenta o valor expandido de 'self' e 'that'. Isto permite-lhe ver a equação real que será gerada, para que você (e o Expression Manager) possa validar que as variáveis existem. Isto pode parecer confuso, uma vez que poderá ver equações bastante extensas. No entanto, se editar a pergunta, verá a equação original com 'self' e/ou 'that'

Note também que não deve usar estas variáveis se (a) quiser nomear explicitamente cada variável utilizada numa equação, ou (b) utilizar variáveis que não têm perguntas secundárias (por exemplo, perguntas de resposta única). Nesses casos, prefixar uma variável com 'that' é excessivo e corre o risco de obter resultados inesperados.

Utilização de NAOK

NAOK --> "Not Applicable" (NA) is alright (OK), ou seja, "Não aplicável" é aceitável

Utilizar NAOK significa que todas ou algumas das variáveis são irrelevantes (ou seja, "Não aplicável" (NA) é aceitável (OK)).

Quando inclui uma variável de uma pergunta numa equação: se essa pergunta (ou pergunta secundária) estiver oculta por uma condição, toda a equação fica desativada.

Por exemplo: count(Q1_SQ1,Q1_SQ2,Q1_SQ3,Q1_SQ4) devolve sempre uma cadeia de caracteres vazia se uma pergunta secundária de Q1 estiver filtrada. Para contar o número de perguntas secundárias selecionadas numa pergunta deste tipo, pode usar count(Q1_SQ1.NAOK,Q1_SQ2.NAOK,Q1_SQ3.NAOK,Q1_SQ4.NAOK). Se a pergunta secundária estiver oculta, o Expression Manager devolve uma cadeia de caracteres vazia.

Sem NAOK: se uma pergunta ou uma pergunta secundária estiver oculta, o Expression Manager devolve sempre uma cadeia de caracteres vazia, o que equivale a devolver falso.

O sufixo .shown utiliza sempre o sistema NAOK (cadeia de caracteres vazia se estiver oculta), mas se precisar do código da resposta, é sempre boa ideia adicionar .NAOK a seguir ao código da pergunta, exceto se precisar do comportamento contrário e souber o que está a fazer.

Pode encontrar outro exemplo e mais informações em Substituição de condições em cascata

Acesso a funções

O Expression Manager dá acesso a funções matemáticas, de cadeias de caracteres e definidas pelo utilizador, como se mostra abaixo. Estas funções têm equivalentes em PHP e JavaScript, para que funcionem de forma idêntica no servidor (PHP) e no cliente (JavaScript). É fácil adicionar novas funções.

Funções implementadas

Estão atualmente disponíveis as seguintes funções:

Função	Significado	Sintaxe
abs	Valor absoluto	number abs(number)
acos	Arco co-seno	number acos(number)
addslashes	Delimitar uma cadeia de caracteres com barras invertidas	string addslashes(string)
asin	Arco seno	number asin(number)
atan	Arco de tangente	number atan(number)
atan2	Arco de tangente com duas variáveis	number atan2(number, number)
ceil	Arredondar frações por excesso	number ceil(number)
checkdate	Devolve verdadeiro (1) se for uma data válida no calendário gregoriano	bool checkdate(month,day,year)
convert_value	Converter um valor numérico utilizando uma tabela de entrada e uma tabela de saída de valores numéricos	number convert_value(fValue, iStrict, sTranslateFromList, sTranslateToList)
cos	Co-seno	number cos(number)
count	Contar o número de perguntas respondidas (não vazias) na lista	number count(arg1, arg12, ..., argN)
countif	Contar o número de perguntas respondidas na lista que são iguais ao primeiro argumento	number countif(matches, arg1, arg2, ... argN)
countifop	Contar o número de perguntas respondidas na lista que satisfazem o critério (arg op valor)	number countifop(op, value, arg1, arg2, ... argN)
date	Formatar a data/hora local	string date(format [, timestamp=time()])
exp	Calcular o expoente de e	number exp(number)
fixnum	Apresentar números com vírgula como separador decimal, se necessário	string fixnum(number)
floor	Arredondar as frações por defeito	number floor(number)
gmdate	Formatar a data/hora GMT	string gmdate(format [, timestamp=time()])
html_entity_decode	Converter todas as entidades HTML nos respetivos caracteres (utiliza sempre ENT_QUOTES e UTF-8)	string html_entity_decode(string)
htmlentities	Converter todos os caracteres aplicáveis em entidades HTML (utiliza sempre ENT_QUOTES e UTF-8)	string htmlentities(string)
expr_mgr_htmlspecialchars	Converter caracteres especiais em entidades HTML (utiliza sempre ENT_QUOTES e UTF-8)	string htmlspecialchars(string)
expr_mgr_htmlspecialchars_decode	Converter entidades HTML especiais de volta em caracteres (utiliza sempre ENT_QUOTES e UTF-8)	string htmlspecialchars_decode(string)
idate	Formatar a hora/data local como inteiro	string idate(string [, timestamp=time()])
if (Updated in 3.0.2 )	if ao estilo do Excel (test,result_if_true[,result_if_false = ""])	if(test,result_if_true[,result_if_false = ""])
implode	Juntar elementos da matriz (array) numa string	string implode(glue,arg1,arg2,...,argN)
intval	Obter o valor inteiro de uma variável	int intval(number [, base=10])
is_empty	Determinar se uma variável é considerada vazia	bool is_empty(var)
is_float	Verifica se o tipo de uma variável é float	bool is_float(var)
is_int	Verifica se o tipo de uma variável é inteiro	bool is_int(var)
is_nan	Verifica se um valor não é um número	bool is_nan(var)
is_null	Verifica se uma variável não é nula	bool is_null(var)
is_numeric	Verifica se uma variável é um número ou uma cadeia de caracteres numérica	bool is_numeric(var)
is_string	Verifica se o tipo de uma variável é cadeia de caracteres	bool is_string(var)
join (New in 2.0 build 130129)	Juntar elementos numa nova cadeia de caracteres	join(arg1, arg2, ... argN)
list	Devolver uma lista, separada por vírgulas, dos valores não vazios	string list(arg1, arg2, ... argN)
listifop (New in 3.16.1 )	Devolver uma lista, separada pelo 'glue' indicado, da propriedade especificada (retProp) das perguntas da lista que satisfazem o critério (cmpProp op valor)	string listifop(cmpProp, op, value, retProp, glue, sgqa1, sgqa2, ... sgqaN)
log	O logaritmo do número na base indicada, se fornecida, ou o logaritmo natural.	number log(number,base=e)
ltrim	Remover espaços em branco (ou outros caracteres) do início de uma cadeia de caracteres	string ltrim(string [, charlist])
max	Localizar o valor mais elevado	number max(arg1, arg2, ... argN)
min	Localizar o valor mais baixo	number min(arg1, arg2, ... argN)
mktime	Obter o timestamp UNIX de uma data (cada um dos 6 argumentos é opcional)	number mktime([hour [, minute [, second [, month [, day [, year ]]]]]])
modulo-function	A função módulo ainda não é suportada. Pode utilizar a função floor() em alternativa	floor(x/y)==(x/y)
nl2br	Insere quebras de linha HTML antes de todas as mudanças de linha numa cadeia de caracteres	string nl2br(string)
number_format	Formatar o número com separador de centenas	string number_format(number)
pi	Obter valor de pi	number pi()
pow	Expressão exponencial	number pow(base, exp)
quoted_printable_decode	Converter uma cadeia de caracteres quoted-printable numa cadeia de caracteres de 8 bits	string quoted_printable_decode(string)
quoted_printable_encode	Converter uma cadeia de caracteres de 8 bits numa cadeia de caracteres quoted-printable	string quoted_printable_encode(string)
quotemeta	Citar de metacarateres	string quotemeta(string)
rand	Gerar um inteiro aleatório, veja este exemplo	int rand() OR int rand(min, max)
regexMatch	comparar uma cadeia de caracteres com uma expressão regular	bool regexMatch(pattern,input)
round	Arredonda um número a uma precisão opcional	number round(val [, precision])
rtrim	Remover espaços em branco (ou outros caracteres) do fim de uma cadeia de caracteres	string rtrim(string [, charlist])
sin	Seno	number sin(arg)
sprintf	Devolve um string formatado	string sprintf(format, arg1, arg2, ... argN)
sqrt	Raiz quadrada	number sqrt(arg)
stddev	Calcular o desvio padrão da amostra para a lista de números	number stddev(arg1, arg2, ... argN)
str_pad	Preencher uma cadeia de caracteres até um determinado comprimento com outra cadeia de caracteres	string str_pad(input, pad_length [, pad_string])
str_repeat	Repetir uma cadeia de caracteres	string str_repeat(input, multiplier)
str_replace	Substituir todas as ocorrências da cadeia de caracteres pesquisada pela cadeia de substituição	string str_replace(search, replace, subject)
strcasecmp	Comparação em modo binário, sem fazer distinção entre maiúsculas e minúsculas, de cadeias de caracteres	int strcasecmp(str1, str2)
strcmp	Comparação em modo binário de cadeias de caracteres	int strcmp(str1, str2)
strip_tags	Remover tags HTML e PHP de uma cadeia de caracteres	string strip_tags(str, allowable_tags)
stripos	Pesquisar a posição da primeira ocorrência de uma cadeia de caracteres unicode, sem distinguir maiúsculas de minúsculas (começa em 0, devolve falso se não for encontrada)	int stripos(haystack, needle [, offset=0])
stripslashes	Retira aspas de um string com aspas	string stripslashes(string)
stristr	Não sensível a Maiúsculas e minúsculas strstr	string stristr(haystack, needle [, before_needle=false])
strlen	Obter comprimento da cadeia de caracteres	int strlen(string)
strpos	Pesquisar a posição da primeira ocorrência de uma cadeia de caracteres unicode (começa em 0, devolve falso se não for encontrada)	int strpos(haystack, needle [ offset=0])
strrev	Inverter uma cadeia de caracteres	string strrev(string)
strstr	Encontrar primeira ocurrência de um string	string strstr(haystack, needle[, before_needle=false])
strtolower	Converter uma cadeia de caracteres para minúsculas	string strtolower(string)
strtotime	Converter quase qualquer descrição textual de data/hora em inglês num timestamp UNIX	int strtotime(string)
strtoupper	Converter uma cadeia de caracteres para maiúsculas	string strtoupper(string)
substr	Devolver parte de uma cadeia de caracteres unicode	string substr(string, start [, length])
sum	Calcular a soma de valor num array	number sum(arg1, arg2, ... argN)
sumifop	Somar os valores das perguntas respondidas na lista que satisfazem o critério (arg op valor)	number sumifop(op, value, arg1, arg2, ... argN)
tan	Tangente	number tan(arg)
time	Devolver o timestamp UNIX atual	number time()
trim	Remover espaços em branco (ou outros caracteres) do início e do fim de uma cadeia de caracteres	string trim(string [, charlist])
ucwords	Converter para maiúscula o primeiro caractere de cada palavra de uma cadeia de caracteres	string ucwords(string)
unique	Devolve verdadeiro se todas as respostas não vazias forem unicas	boolean unique(arg1, ..., argN)

Funções planeadas ou em consideração

Outras funções que estão planeadas (ou em consideração), mas que ainda não foram implementadas, incluem as seguintes. Algumas destas destinam-se a manter a compatibilidade com outra ferramenta de inquéritos.

Sintaxe	Significado	Comentários
e()	devolve o valor de e
formatDate(X,PAT)	devolve o valor em cadeia de caracteres da data X formatada de acordo com o padrão de formato de data Java PAT
formatNumber(X,PAT)	devolve o valor em cadeia de caracteres do número X formatado de acordo com o padrão de formato numérico Java PAT
getAnsOption(X)	Plugin Principal ExpressionAnswerOptions
getAnsOption(X,Y)	Plugin Principal ExpressionAnswerOptions
getRelevance(X)	devolve a equação de relevância da pergunta X
getStartTime()	devolve a data correspondente à hora do sistema em que a entrevista foi iniciada
getType(X)	devolve o nome, em cadeia de caracteres, do tipo de dados - por exemplo, *NA* se isNA()
gotoFirst()	salta para o primeiro conjunto de perguntas relevantes - isto viola o fluxo normal do sistema
gotoNext()	salta para o conjunto seguinte de perguntas relevantes - isto viola o fluxo normal do sistema
gotoPrevious()	salta para o conjunto anterior de perguntas relevantes - isto viola o fluxo normal do sistema
isAsked(X)	devolve verdadeiro se a resposta não for *NA*, *INVALID* nem *UNASKED*
isInvalid(X)	devolve verdadeiro se a resposta for do tipo *INVALID*
isNA(X)	devolve verdadeiro se a resposta for do tipo *NA*
isNotUnderstood(X)	devolve verdadeiro se a resposta for do tipo *HUH*
isRefused(X)	devolve verdadeiro se a resposta for do tipo *REFUSED*
isSpecial(X)	devolve verdadeiro se a resposta for do tipo *UNASKED*, *NA*, *REFUSED*, *INVALID*, *UNKNOWN* ou *HUH*
isUnknown(X)	devolve verdadeiro se a resposta for do tipo *UNKNOWN*
jumpTo(X)	salta para o grupo que contém a pergunta indicada -- isto viola o fluxo normal do sistema
jumpToFirstUnasked()	salta para a primeira pergunta não colocada ignorando assim as perguntas já respondidas isto viola o fluxo normal do sistema
lastIndexOf(X,Y)	devolve o último índice (base 0) da cadeia de caracteres Y na cadeia de caracteres X. Devolve -1 se Y não estiver contida em X
list(X,...)	uma cadeia de caracteres com uma lista, separada por vírgulas, dos valores positivos, com "e" a separar os dois últimos
mean(X,...)	devolve a média de uma lista de valores
numAnsOptions(X)	devolve o número de opções de resposta que a pergunta X tem
orlist(X,...)	uma cadeia de caracteres com uma lista, separada por vírgulas, dos valores positivos, com "ou" a separar os dois últimos
parseDate(X,PAT)	devolve o valor de data da cadeia de caracteres X interpretada com o padrão de formato de data Java PAT
parseNumber(X,PAT)	devolve o valor numérico da cadeia de caracteres X interpretada com o padrão de formato numérico Java PAT
showAllResponsesExcept( questionList,attributeList,attributeTitleList)	questionList = lista de identificadores de perguntas delimitada por barras verticais; attributeList = lista de atributos delimitada por barras verticais (como question#, title, text, type - para poder decidir o que mostrar); attributeTitleList = lista de cabeçalhos de tabela delimitada por barras verticais, para poder internacionalizar o relatório.
showTheseResponses( questionList,attributeList,attributeTitleList)	questionList = lista de identificadores de perguntas delimitada por barras verticais; attributeList = lista de atributos delimitada por barras verticais (como question#, title, text, type - para poder decidir o que mostrar); attributeTitleList = lista de cabeçalhos de tabela delimitada por barras verticais, para poder internacionalizar o relatório.

O Expression Manager sabe quais as variáveis locais

Para construir corretamente o JavaScript de uma página, o Expression Manager precisa de saber quais as variáveis definidas na página e qual o respetivo ID JavaScript (por exemplo, para document.getElementById(x)). Também tem de saber quais as variáveis definidas noutras páginas (para poder garantir que os campos <input type='hidden' value='x'> necessários estão presentes e preenchidos).

Condições em cascata

Se alguma das variáveis for irrelevante, toda a equação será irrelevante (falsa). Por exemplo, na tabela seguinte, N/A significa que uma das variáveis não era relevante

Operador	Exemplo	a	b	Resultado
+ (unary)	+a	N/A		false
!	!a	N/A		false
== (or eq)	a == b	N/A	5	false
== (or eq)	a == b	N/A	0	false
== (or eq)	a == b	N/A	N/A	false
!= (or ne)	a != b	N/A	5	false
!= (or ne)	a != b	N/A	N/A	false
!= (or ne)	a != b	N/A	0	false
> (or gt)	a > b	N/A	5	false
>= (or ge)	a >= b	N/A	5	false
< (or lt)	a < b	N/A	5	false
<= (or le)	a <= b	N/A	5	false
and	a and b	N/A	5	false
and	a and b	N/A	N/A	false
or	a or b	N/A	N/A	false
or	a or b	N/A	5	false
+	a + b	N/A	5	false
*	a * b	N/A	5	false
/	a / b	5	N/A	false
()	(a)	N/A		false
(exp)	(a && b)	N/A	5	false
(exp) op (exp)	(b + b) > (a && b)	N/A	5	false
function	sum(a,b,b)	N/A	5	false
function	max(a,b)	N/A	5	false
function	min(a,b)	N/A	5	false
function	implode(', ',a,b,a,b)	N/A	5	false
function	if(a,a,b)	N/A	5	false
function	is_empty(a)	N/A		false
function	is_empty(a)	0 (or blank)		true
function	!is_empty(a)	N/A		false

Substituir as condições em cascata

Imagine que pretende mostrar um total acumulado de todas as respostas relevantes. Poderá tentar utilizar a equação {sum(q1,q2,q3,...,qN)}. No entanto, esta é traduzida internamente para LEMif(LEManyNA('q1','q2','q3',...,'qN'),,sum(LEMval('q1'),LEMval('q2'),LEMval('q3'),...,LEMval('qN'))). Assim, se algum dos valores q1-qN for irrelevante, a equação devolverá sempre falso. Neste caso, sum() mostrará 0 até que todas as perguntas sejam respondidas.

Para contornar isto, pode adicionar a cada variável o sufixo ".NAOK" (que significa que Não Aplicável é aceitável). Nestes casos, ocorre o seguinte comportamento. Imagine que tem uma variável q1.NAOK

1. q1 não é adicionada à cláusula LEManyNA()
2. LEMval('q1') continuará a verificar se a resposta é relevante e devolverá '' se não for (assim, as respostas irrelevantes individuais serão ignoradas, mas não invalidarão toda a expressão).

Assim, a solução para o problema do total acumulado é utilizar a equação sum(q1.NAOK,q2.NAOK,q3.NAOK,...,qN.NAOK).

A utilização do sufixo .NAOK também permite aos autores conceber inquéritos que têm vários percursos possíveis, mas que depois convergem em percursos comuns. Por exemplo, imagine que os participantes respondem a um inquérito de uma forma que está fora do intervalo normal de respostas. O autor pode alertá-los de que poderão não obter resultados válidos e perguntar-lhes se pretendem realmente continuar com o inquérito. Se responderem Sim, as restantes perguntas serão apresentadas. A condição para "as restantes perguntas" verificaria se as respostas iniciais estavam dentro do intervalo normal OU se o participante respondeu Sim à pergunta que só é relevante se tiver respondido fora do intervalo normal.

Como é que o Expression Manager suporta a microadaptação condicional?

Eis um exemplo de microadaptação (onde Question Type=='expr' significa uma Equação):

Códigos das perguntas	Relevância	Tipo de pergunta	Pergunta
name	1	text	Qual é o seu nome?
age	1	text	Que idade tem?
badage	!is_empty(age)	expr	{(age<16) or (age>80)}
agestop	badage	message	Lamentamos, {name}, é demasiado {if( (age<16),'jovem',if( (age>80),'idoso','de meia-idade') ) } para este teste.
kids	!badage	yesno	Tem filhos?
parents	1	expr	{!badage && kids=='Y'}
numKids	parents	text	Quantos filhos tem?
kid1	parents && numKids >= 1	text	Que idade tem o seu primeiro filho?
kid2	parents && numKids >= 2	text	Que idade tem o seu segundo filho?
kid3	parents && numKids >= 3	text	Que idade tem o seu terceiro filho?
kid4	parents && numKids >= 4	text	Que idade tem o seu quarto filho?
kid5	parents && numKids >= 5	text	Que idade tem o seu quinto filho?
sumage	1	expr	{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK,kid5.NAOK)}
report	parents	yesno	{name}, disse que tem {age} anos e que tem {numKids} filhos. A soma das idades dos seus primeiros {min(numKids,5)} filhos é {sumage}

Todas estas perguntas podem estar numa única página (por exemplo, no mesmo grupo) e só as perguntas relevantes serão apresentadas. Além disso, à medida que introduz as idades dos filhos, a expressão sum() da última pergunta será atualizada dinamicamente na página.

O Expression Manager disponibiliza esta funcionalidade envolvendo cada expressão num elemento <span> com nome. Sempre que um valor muda, recalcula a expressão que deve aparecer nesse elemento <span> e regenera a apresentação. Pode ter dezenas, ou mesmo centenas, dessas expressões adaptadas na mesma página, e a página voltará a apresentá-las todas numa única atualização do ecrã.

Correspondência entre o LimeSurvey 1.91+ e as funcionalidades do Expression Manager

Funcionalidade antiga	Nova funcionalidade	Comentários
Condições	Relevância	Pode utilizar equações condicionais muito complexas e aceder a uma gama mais vasta de variáveis
Avaliações	Equação	Qualquer pontuação de avaliação pode ser reestruturada numa Equação. Isto garante que a pontuação é gravada na base de dados e permite também ver as alterações dinâmicas do valor da pontuação na página atual
Substituições	Expression Manager	O motor principal recebe a cadeia de caracteres de entrada e trata tudo o que estiver entre chavetas como uma Expressão - pelo que trata todos os tipos de substituições históricos. Para não interferir com o JavaScript incorporado, o Expression Manager só processa o conteúdo entre chavetas desde que (a) não haja espaços em branco no início ou no fim dentro das chavetas - por exemplo, {expr} é uma expressão, mas { expr}, {expr } e { expr } não são expressões. Além disso, o Expression Manager não processa o conteúdo dentro das suas próprias cadeias de caracteres (por exemplo, {list('hi','there {braces}')} gera "hi there {braces}"). Também ignora chavetas com escape (por exemplo, \{this is not an expression\})
Validação	Expression Manager	O plano é pegar nos atuais Atributos da pergunta de mínimo/máximo e fazer com que o Expression Manager os processe. Dessa forma, os valores mínimo/máximo podem ser eles próprios expressões

Realce de sintaxe

Para ajudar a introduzir e validar expressões, o EM disponibiliza o realce de sintaxe com as seguintes funcionalidades:

Tipos e significados do realce de sintaxe

Cor	Exemplo	Significado	Dica	Comentários
fundo bege	Exemplo	a equação completa	nenhuma	Tudo o que estiver entre chavetas e for reconhecido como uma equação (por exemplo, sem espaços em branco no início ou no fim) será realçado com um fundo bege para o distinguir do texto envolvente
texto vermelho a negrito	Exemplo	Um erro	Alguma explicação sobre o erro	Pode ser uma variável desconhecida ou um erro numa função, .... O inquérito pode ficar totalmente inutilizável, mas isto não é mostrado ao utilizador público.
texto azul	Exemplo	nome de função	significado e sintaxe permitida	os nomes de funções, ou elementos que deveriam ser funções por serem seguidos de um parêntese de abertura, são apresentados em texto azul a negrito. As dicas mostram o significado e a sintaxe permitida da função.
texto cinzento	Exemplo	cadeia de caracteres	nenhuma	as cadeias de caracteres entre aspas simples e duplas são mostradas em texto cinzento
texto ciano	Exemplo	variável definida na mesma página,	[nome ou código SGQA]: pergunta; valor; lista de respostas com os códigos de cada valor	Qualquer variável definida na mesma página da pergunta atual é mostrada em texto ciano, indicando que pode ser atualizada em JavaScript. A dica mostra o seu nome, a pergunta propriamente dita e o seu valor atual (ou vazio, se não estiver definido). Se o tipo de pergunta esperar respostas de um conjunto de valores enumerados, é mostrado o mapeamento dos códigos para os valores apresentados.
texto verde	Exemplo	variável definida numa página anterior	[nome ou código SGQA]: pergunta; valor; lista de respostas com os códigos de cada valor	Qualquer variável definida numa página anterior é mostrada em texto verde a negrito. A dica mostra o seu nome, a pergunta propriamente dita e o seu valor atual (ou vazio, se não estiver definido). Se o tipo de pergunta esperar respostas de um conjunto de valores enumerados, é mostrado o mapeamento dos códigos para os valores apresentados.
texto rosa a negrito	Exemplo	variável definida numa página posterior em geral: vazia no início do inquérito, mas pode ser preenchida através do índice ou ao retroceder	[nome ou código SGQA]: pergunta; valor; lista de respostas com os códigos de cada valor	Qualquer variável definida numa página seguinte é mostrada em texto rosa a negrito. A dica mostra o seu nome, a pergunta propriamente dita e o seu valor atual (ou vazio, se não estiver definido). Se o tipo de pergunta esperar respostas de um conjunto de valores enumerados, é mostrado o mapeamento dos códigos para os valores apresentados.
texto castanho a negrito	Exemplo	um valor de substituição do Lime	o valor	As cadeias de substituição do Lime (como {TOKEN:xxx}, {PRIVACY_MESSAGE}) são mostradas em texto castanho a negrito.
texto vermelho	Exemplo	operador de atribuição (=)	mensagem de aviso	Se utilizar o operador de atribuição (=), esse operador será apresentado em texto vermelho. Isto serve para ajudar a evitar reatribuições acidentais de valores quando na realidade pretendia verificar se a == b em vez de definir o valor de a = b.
texto preto normal	Exemplo	pontuação	nenhuma	Toda a restante pontuação dentro da expressão é mostrada em texto preto normal.
texto com caixa vermelha	uma linha vermelha a negrito rodeia o erro	erro de sintaxe	descrição do erro	Os erros de sintaxe detetados são mostrados rodeando o erro com uma caixa vermelha. A dica mostra o erro. Os exemplos incluem parênteses não correspondentes, utilização de funções não definidas, passagem de um número errado de argumentos às funções, expressões mal estruturadas (por exemplo, operadores em falta entre variáveis), tentativa de atribuir um novo valor a uma variável só de leitura, tentativa de atribuir valores a elementos que não são variáveis, ou utilização de sintaxe não suportada. Note que o sistema de deteção de erros de sintaxe pode comunicar apenas um erro numa expressão, mesmo que existam vários; no entanto, se forem detetados erros, será mostrado pelo menos um.