ExpressionScript Engine - Guia de início rápido

Guia de início rápido

No LimeSurvey, pode personalizar ainda mais os seus inquéritos através do ExpressionScript (abreviatura: ES). Nota: "O ExpressionScript era designado por Expression Manager (EM) em versões anteriores. Se encontrar a designação Expression Manager em algum lugar, trata-se apenas do nome antigo do ES."

O ES pode ser utilizado para especificar o seguinte:

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

O ES 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.

Atualmente, o ES dá acesso a 70 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 por humanos (em vez de nomes SGQA).

As secções seguintes mostram os principais locais onde o ES é utilizado.

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

Alguns inquéritos utilizam a "Lógica Goto", de modo que, se responder à Pergunta1 com a opção C, é redirecionado para a Pergunta5. Esta abordagem é muito limitada, pois é difícil de validar. Além disso, quebra-se facilmente quando é necessário reordenar perguntas. Por outro lado, o ES utiliza equações de relevância booleanas 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.

Nota: Isto é semelhante ao que pode ser feito através do editor de condições, mas o ES permite especificar facilmente critérios muito mais complexos e poderosos (e permite utilizar o nome da variável em vez de identificadores SGQA).

---

Para compreender melhor o conceito de relevância, vamos analisar o seguinte inquérito, que calcula o Índice de Massa Corporal (IMC) dos participantes. Para o descarregar, clique na seguinte hiperligação: Exemplo de inquérito de Índice de Massa Corporal.

A equação de relevância é apresentada abaixo, na coluna Relevância, depois do nome da variável. Os valores de relevância de weight, weight_units, height e height_units são todos 1 (valor por defeito), o que significa que essas perguntas são sempre apresentadas. No entanto, a relevância de BMI é {!is_empty(height) and !is_empty(weight)}, o que significa que o IMC só será calculado se o participante introduzir um valor tanto para a altura como para o peso (evitando assim o risco de obter um erro de divisão por zero). Além disso, a pergunta "Report" só é apresentada se o participante responder às quatro perguntas principais (height, heightunits, weight, weightunits).

Nota: A imagem acima provém do ficheiro de lógica do inquérito, que permite procurar erros de sintaxe antes de ativar o inquérito.

A relevância é apresentada e editável quando:

• pretende ver/editar a relevância ao nível da pergunta
• pretende ver/editar a relevância ao nível do grupo

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

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

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

Tenha em atenção que não deve utilizar chavetas ao introduzir uma equação de relevância.

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

Vamos agora analisar outro exemplo - um inquérito de recenseamento simples. Para o descarregar, clique na seguinte hiperligação: Exemplo de 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 de um coabitante (é apresentada para a segunda pessoa que coabita consigo). Além disso, p2name, p2age e p2sum só são apresentadas se a pergunta anterior a cada uma delas contiver uma resposta.

Assim, o grupo também tem critérios de relevância ao nível da pergunta, de modo que algumas perguntas só aparecem se tiver respondido a certas perguntas anteriores (por exemplo, p2age é apresentada se p2name tiver sido respondida). O ES combina por si a relevância ao nível do grupo e da pergunta. As perguntas de um grupo só são colocadas se o grupo no seu todo for relevante. Depois, só é colocado o subconjunto de perguntas dentro do grupo que são relevantes.

Eis a captura de ecrã para editar a relevância ao nível do grupo de Cohabitant 2:

Tenha em atenção que não se usam chavetas ao introduzir uma equação de relevância.

Personalização/Piping

O ES permite-lhe fazer facilmente personalizações condicionais simples e complexas. Por vezes, basta uma substituição simples, como dizer: "Disse que comprou [Produto]. De que gostou mais 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 usar "Sr. ou Sra." com base no género da pessoa. Noutras situações, precisa de uma substituição ainda mais complexa (por exemplo, baseada num cálculo matemático). O ES suporta todos estes tipos de personalização/piping.

Equações condicionais

O exemplo do Índice de Massa Corporal (IMC) mostra a capacidade de calcular o IMC de uma pessoa, mesmo permitindo que esta introduza a altura e o peso em duas unidades diferentes (cm vs polegadas e kg vs lb):

Neste caso, weightkg é {if(weightunits == "kg", weight, weight * 0.453592)}. Esta função "if()" significa que, se o participante introduzir o peso em quilogramas, é utilizado esse valor; caso contrário, o valor introduzido (a alternativa são libras) é multiplicado por 0.453592 para o converter em quilogramas. A variável heightm utiliza uma abordagem semelhante para calcular a altura da pessoa em metros (altura em cm/100), mesmo que a altura tenha sido introduzida em polegadas (1 metro = 3.28084 polegadas).

O IMC é calculado da seguinte forma: {weightkg / (heightm * heightm)}.

Por fim, o relatório personaliza condicionalmente a mensagem para o participante, indicando-lhe o que introduziu (por exemplo, "Disse que mede 2 metros e pesa 70 kg.")

Na imagem abaixo, weightstatus utiliza instruções "if()" aninhadas para categorizar a pessoa, desde abaixo do peso até obesidade grave. Pode ver a sua equação consultando a respetiva lógica:

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

1. A personalização exige que as expressões estejam entre chavetas
2. As expressões podem ocupar várias linhas se, como neste caso, pretender 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.

O relatório do IMC tem o seguinte aspeto:

Aqui está a janela de edição da mesma pergunta.

Tudo o que estiver entre chavetas é tratado como uma expressão, com realce de sintaxe (codificação por cores) na imagem anterior. Se existirem erros de escrita (como nomes de variáveis ou funções incorretos ou não definidos), o ES apresentará um erro. No exemplo abaixo:

• heightunit.shown é um nome de variável não definido (na verdade, é heightunits.shown) e
• "rnd()" é uma função não definida (o nome correto da função é "round()").

Em ambos os casos, os erros estão localizados dentro de uma caixa vermelha para facilitar a sua deteção e correção.

Pode também 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 exige que as expressões estejam entre chavetas, para que o LimeSurvey saiba quais as partes da pergunta que são texto livre e quais devem ser analisadas pelo motor do ExpressionScript.

Validação

O ES 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 cadeia de caracteres especificados. Qualquer valor num destes campos é considerado uma expressão, pelo que pode definir critérios de mínimo/máximo com relações condicionais complexas com outras perguntas.

Em todos estes casos, uma vez que o atributo avançado da pergunta é sempre considerado uma expressão, não se usam chavetas ao especificá-lo.

A página de inquéritos de exemplo mostra muitos exemplos funcionais com uma variedade de expressões de validação.

ExpressionScript - apresentação

Para saber mais sobre o ExpressionScript e como pode utilizar diferentes expressões para melhorar o seu inquérito, clique na seguinte hiperligação.