ExpressionScript Engine - Guia de início rápido
From LimeSurvey Manual
Guia de início rápido
No LimeSurvey, você pode personalizar ainda mais seus inquéritos por meio do uso do ExpressionScript (abreviado: ES). Observação: "O ExpressionScript era chamado de Expression Manager (EM) em versões anteriores. Se você encontrar Expression Manager em algum lugar, é apenas o nome antigo do ES."
O ES pode ser usado para especificar o seguinte:
- Navegação/Ramificação - permite que as respostas de um respondente alterem a ordem em que as perguntas são exibidas;
- Personalização/Piping - ajuda você a formular a pergunta (por exemplo, referindo-se 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);
- Validação - garante que as respostas atendam a certos critérios, como valores mínimos e máximos ou um determinado padrão de entrada.
O ES oferece uma maneira intuitiva de especificar a lógica de cada um desses recursos. Quase tudo o que você pode escrever como uma equação matemática padrão é uma expressão válida.
Atualmente, o ES oferece acesso a 70 funções e pode ser facilmente estendido para oferecer suporte a mais. Ele também permite acessar suas variáveis usando nomes de variáveis legíveis por humanos (em vez de nomes SGQA).
As próximas seções mostram os principais locais onde o ES é usado.
Alguns inquéritos usam a "Lógica Goto", de modo que, se você responder à Pergunta1 com a opção C, será redirecionado para a Pergunta5. Essa abordagem é muito limitada, pois é difícil de validar. Além disso, ela quebra facilmente quando é necessário reordenar as perguntas. Por outro lado, o ES usa equações booleanas de relevância para especificar todas as condições em que uma pergunta pode ser válida. Se a pergunta for relevante, ela é exibida; caso contrário, não é aplicável e o valor "NULL" é armazenado no banco de dados.
Para entender melhor o conceito de relevância, vamos nos concentrar no inquérito a seguir, que calcula o Índice de Massa Corporal (IMC) dos respondentes. Para baixá-lo, clique na seguinte hiperligação: Exemplo de inquérito de Índice de Massa Corporal.
A equação de relevância é mostrada abaixo na coluna Relevância, após o nome da variável. Os valores de relevância de weight, weight_units, height e height_units são todos 1 (valor padrão), o que significa que essas perguntas são sempre exibidas. 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 inserir um valor para altura e peso (evitando assim o risco de um erro de divisão por zero). Além disso, a pergunta "Report" só é exibida se o respondente responder às quatro perguntas principais (height, heightunits, weight, weightunits).
Nota: A imagem acima vem do arquivo de lógica do inquérito, que permite procurar erros de sintaxe antes de ativar o inquérito.
A relevância é exibida e editável quando:
- você deseja visualizar/editar a relevância no nível da pergunta
- você deseja visualizar/editar a relevância no nível do grupo
Visualizando / editando a relevância no nível da pergunta
Esta equação calcula o Índice de Massa Corporal (IMC). Ela só é perguntada se a pessoa inserir sua altura e peso.
Esta é a tela de edição da pergunta "BMI".
Observe que você não usa chaves ao inserir uma equação de relevância.
Visualizando / editando a relevância no nível do grupo
Vamos nos concentrar agora em outro exemplo - um inquérito de censo simples. Para baixá-lo, clique na seguinte hiperligação: Exemplo de inquérito de censo.
A primeira página pergunta quantas pessoas moram com você e armazena o valor na variável "cohabs". Esta página só é exibida se houver mais de um coabitante (ela é exibida para a segunda pessoa que mora com você). Além disso, p2name, p2age e p2sum só são exibidas se a pergunta anterior a cada uma delas contiver uma resposta.
Assim, o grupo também tem critérios de relevância no nível da pergunta, de modo que algumas perguntas só aparecem se você respondeu a determinadas perguntas anteriores (por exemplo, p2age é exibida se p2name foi respondida). O ES combina a relevância de grupo e de pergunta para você. As perguntas de um grupo só são feitas se o grupo como um todo for relevante. Em seguida, apenas o subconjunto de perguntas relevantes dentro do grupo é feito.
Esta é a captura de tela para editar a relevância no nível do grupo de Cohabitant 2:
Observe que você não usa chaves ao inserir uma equação de relevância.
Personalização/Piping
O ES permite realizar facilmente personalizações condicionais simples e complexas. Às vezes, você precisa apenas de uma substituição simples, como dizer: "Você disse que comprou [Produto]. De que você mais gostou nele?". Outras vezes, você precisa de uma substituição condicional, como "[Sr./Sra.] [Sobrenome], você aceitaria responder ao nosso inquérito?". Nesse caso, você quer usar "Sr. ou Sra." de acordo com o gênero da pessoa. Em outros casos, você precisa de substituições ainda mais complexas (como as baseadas em um cálculo matemático). O ES oferece suporte a todos esses tipos de personalização/piping.
Equações condicionais
O exemplo do Índice de Massa Corporal (IMC) mostra como calcular o IMC de uma pessoa, mesmo permitindo que ela informe sua altura e seu peso em duas unidades diferentes (cm ou polegadas, e kg ou lb):
Neste caso, weightkg é {if(weightunits == "kg", weight, weight * 0.453592)}. Esta função "if()" significa que, se o participante informar o peso em quilogramas, esse valor será usado; caso contrário, o valor informado (libras é a alternativa) será multiplicado por 0.453592 para convertê-lo em quilogramas. A variável heightm usa uma abordagem semelhante para calcular a altura da pessoa em metros (altura em cm/100), mesmo que ela tenha informado a altura em polegadas (1 metro = 3.28084 polegadas).
O IMC é calculado como: {weightkg / (heightm * heightm)}.
Por fim, o relatório personaliza condicionalmente a mensagem para o participante, informando o que ele digitou (por exemplo: "Você disse que tem 2 metros de altura e pesa 70 kg.").
Na imagem abaixo, weightstatus usa instruções "if()" aninhadas para classificar a pessoa de abaixo do peso a severamente obesa. Você pode ver sua equação verificando a lógica:
Na janela de edição desta pergunta, você pode ver duas coisas:
- A personalização exige que as expressões estejam entre chaves
- As expressões podem ocupar várias linhas se, como neste caso, você 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 exibidas em caixas de seleção na mesma página da pergunta. Isso ocorre porque a personalização insere uma tag <span>, que não é válida dentro de opções de seleção.O relatório de IMC tem esta aparência:
Esta é a janela de edição da mesma pergunta.
Tudo o que estiver entre chaves é tratado como uma expressão, com destaque de sintaxe (codificação por cores) na imagem anterior. Se houver erros de digitação (como nomes de variáveis ou funções escritos incorretamente ou não definidos), o ES exibirá um erro. No exemplo abaixo:
- heightunit.shown é um nome de variável não definido (o correto é heightunits.shown) e
- "rnd()" é uma função não definida (o nome correto da função é "round()").
Em ambos os casos, os erros são destacados em uma caixa vermelha para facilitar a localização e a correção.
Você também pode ver que é possível criar rapidamente relatórios complexos, como uma tabela de valores informados ou conselhos personalizados.
Lembre-se de que toda personalização deve colocar as expressões entre chaves, para que o LimeSurvey saiba quais partes da pergunta são texto livre e quais devem ser processadas pelo mecanismo ExpressionScript.
Validação
O ES controla o funcionamento da maioria das opções avançadas de pergunta. Elas controlam aspectos como o número mínimo/máximo de respostas, valores individuais mínimos/máximos, valores mínimos/máximos de soma e a verificação de que os valores informados correspondem a padrões de texto especificados. Qualquer valor em um desses campos é considerado uma expressão, portanto você pode definir critérios mínimos/máximos com relações condicionais complexas com outras perguntas.
Em todos esses casos, como o atributo avançado de pergunta é sempre considerado uma expressão, você não usa chaves ao especificá-lo.
A página de inquéritos de exemplo mostra vários exemplos funcionais com uma variedade de expressões de validação.
ExpressionScript - apresentação
Para saber mais sobre o ExpressionScript e como você pode usar diferentes expressões para aprimorar seu inquérito, clique na seguinte hiperligação.