Tutoriais do ExpressionScript

Visão geral do que foi explicado anteriormente

Se você acompanhou até aqui a estrutura do manual do LimeSurvey, isso significa que já conhece a terminologia do LimeSurvey. Em seguida, abordamos expressões e variáveis para aprender a aprimorar nossas pesquisas. Na parte seguinte, passamos aos tipos e significados do destaque de sintaxe para aprender a corrigir erros de sintaxe.

Com essas noções básicas abordadas, podemos avançar para exemplos e explicar como as expressões funcionam no LimeSurvey.

Destaque de sintaxe

As capturas de tela a seguir dão exemplos, mas não mostram os valores das dicas de ferramenta. Uma dica de ferramenta (tooltip) é uma caixa informativa exibida sempre que você passa o mouse sobre qualquer palavra colorida em negrito.

Graças a esse destaque de sintaxe, é muito fácil compor expressões corretas, mesmo as complicadas. Embora a equipe do LimeSurvey pretenda tentar criar uma interface gráfica (GUI) para construir expressões, você pode usar o destaque de sintaxe existente para identificar e corrigir erros de digitação rapidamente. Você também pode usar as dicas de ferramenta para validar a precisão de suas expressões (por exemplo, confirmar que selecionou a(s) variável(is) desejada(s)).

Em cada um dos exemplos, há três colunas:

1. Source (Origem) - este é o texto bruto que você digitaria no campo de pergunta do LimeSurvey
2. Pretty Print (Formatado) - este é o equivalente com destaque de sintaxe do que você digitou
   • Observe que as expressões são exibidas com fundo bege, mas sem chaves ao redor neste destaque.
   • Como o EM oferece suporte à substituição recursiva, exibir chaves no destaque causaria erros de sintaxe
3. Result (Resultado) - esta é a saída gerada quando o EM processa a origem
   • Tudo o que puder ser substituído corretamente é substituído
   • As expressões com erros são exibidas em linha, com destaque de sintaxe. Os erros são cercados por uma caixa com contorno vermelho.

Sintaxe correta

Veja abaixo exemplos de sintaxe correta:

1. Values (Valores): mostra que as variáveis conhecidas são codificadas por cores conforme estejam definidas ou não na página atual.
2. Question Attributes (Atributos da questão): mostra que a notação de ponto pode acessar algumas propriedades das perguntas
3. Math (Matemática): mostra que cálculos básicos e complexos são suportados
4. TextProcessing (Processamento de texto): mostra algumas das funções de processamento de texto disponíveis
5. Dates (Datas): mostra duas das funções relacionadas a datas disponíveis
6. Conditional (Condicional): mostra o uso da função if(). As opções podem ser aninhadas.
7. Tailored paragraph (Parágrafo personalizado): você pode personalizar completamente um relatório com base em valores anteriores
8. EM processes within strings (O EM processa dentro de strings): mostra que ele pode fazer substituições dentro de strings. Este exemplo gera um nome de imagem personalizado.
9. EM doesn't process curly braces like these (O EM não processa chaves como estas): mostra que, se as chaves forem escapadas, ou houver um espaço em branco entre a expressão e as chaves, o ES ignora a expressão.

Sintaxe do EM contendo erros

Veja exemplos de erros comuns ao digitar expressões do ES. Observe que as dicas de ferramenta fornecem informações adicionais.

1. JavaScript em linha que esqueceu de adicionar espaços após a chave
   • Como "document.write" aparece logo após uma chave, o EM acha que é uma expressão e coloca "document" e "write" em caixas vermelhas, pois são, respectivamente, uma variável e uma função não definidas
2. Variáveis, funções e operadores desconhecidos/com erros de ortografia
   • Aqui esquecemos que estamos usando o nome de variável "gender" em vez de "sex", mas o EM detecta esse erro. Ele também coloca '++' em uma caixa vermelha, pois não é um operador suportado.
3. Avisa se você usar = em vez de eq, ou realizar atribuições de valor
   • Observe que '=' e '+=' estão em texto vermelho em vez de preto. Se você passar o mouse sobre eles, verá avisos de que está atribuindo um valor.
4. Número incorreto de argumentos para funções
   • if() recebe 3 argumentos, mas foram fornecidos 4; portanto, passar o mouse sobre o "if" em caixa vermelha explicará o erro e mostrará a sintaxe suportada
   • sum() aceita um número ilimitado de argumentos, mas havia uma vírgula final antes do parêntese de fechamento, então ela fica em caixa vermelha
5. Parênteses não correspondentes
   • Este é um dos erros mais comuns ao escrever expressões.
   • Isso mostra dois exemplos de parênteses de fechamento ausentes e um exemplo de um parêntese de fechamento a mais.
6. Sintaxe não suportada
   • Se você usar um operador ou pontuação que o ES não suporta, ele o colocará em uma caixa vermelha.
7. Atribuições inválidas
   • Algumas variáveis são de leitura e escrita (readWrite) e podem ter seus valores alterados. Outras são somente leitura.
   • Se você tentar alterar o valor de uma variável somente leitura, não será possível. O EM colocará a tentativa em uma caixa vermelha.
   • Se você tentar atribuir um valor a uma equação ou a uma string, também receberá um erro

Exemplos "ao vivo" de destaque de sintaxe com dicas de ferramenta ativas

Source	Pretty Print	Result
Here is an example of OK syntax with tooltips Hello {if(gender=='M','Mr.','Mrs.')} {surname}, it is now {date('g:i a',time())}. Do you know where your {sum(numPets,numKids)} children and pets are?	Here is an example of OK syntax with tooltips Hello if(gender == 'M','Mr.','Mrs.') surname, it is now date('g:i a',time()). Do you know where your sum(numPets,numKids) children and pets are?	Here is an example of OK syntax with tooltips Hello Mr. Smith, it is now 6:07 am. Do you know where your 3 children and pets are?
Here are common errors so you can see the tooltips Variables used before they are declared: {notSetYet} Unknown Function: {iff(numPets>numKids,1,2)} Unknown Variable: {sum(age,num_pets,numKids)} Wrong # parameters: {sprintf()},{if(1,2)},{date()} Assign read-only-vars:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Unbalanced parentheses: {pow(3,4},{(pow(3,4)},{pow(3,4))}	Aqui estão erros comuns para que você veja as dicas de ferramenta Variáveis usadas antes de serem declaradas: notSetYet Função desconhecida: iff(numPets > numKids,1,2) Variável desconhecida: sum(age,num_pets,numKids) Número incorreto de parâmetros: sprintf(),if(1,2),date() Atribuição a variáveis somente leitura:TOKEN:ATTRIBUTE_1+=10,name='Sally' Parênteses desbalanceados: pow(3,4,(pow(3,4),pow(3,4))	Aqui estão erros comuns para que você veja as dicas de ferramenta Variáveis usadas antes de serem declaradas: notSetYet Função desconhecida: iff(numPets > numKids,1,2) Variável desconhecida: sum(age,num_pets,numKids) Número incorreto de parâmetros: sprintf(),if(1,2),date() Atribuição a variáveis somente leitura:TOKEN:ATTRIBUTE_1+=10,name='Sally' Parênteses desbalanceados: pow(3,4,(pow(3,4),pow(3,4))
Here is some of the unsupported syntax No support for '++', '--', '%',';': {min(++age, --age,age % 2);} Nor '|', '&', '^': {(sum(2 | 3,3 & 4,5 ^ 6)}} Nor arrays: {name[2], name['mine']}	Here is some of the unsupported syntax No support for '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Nor '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Nor arrays: name [ 2 ] ,name [ 'mine' ]	Here is some of the unsupported syntax No support for '++', '--', '%',';': min( ++ age, -- age,age % 2) ; Nor '|', '&', '^': (sum(2 | 3,3 & 4,5 ^ 6)} Nor arrays: name [ 2 ] ,name [ 'mine' ]

Exemplos de personalização

"Prezado(a) {Sr.}/{Sra.} Smith..."

Use a função if() para escolher condicionalmente se 'Sr.' ou 'Sra.' será exibido.

A sintaxe é if(teste,fazer_se_verdadeiro,fazer_se_falso).

#	Código	Pergunta	Tipo
1	gender	Qual é o seu sexo?	Sexo
2	example1	Prezado(a) {if(gender=='M','Mr.','Mrs.')} Smith, ...	Texto livre longo

Como pode ser observado abaixo, "Sr." e "Sra." são adaptados conforme a resposta selecionada pelo respondente para a pergunta "gender".

"Prezado(a) {Sr.}/{Sra.} Smith..." no convite por e-mail

Você pode usar o exemplo acima no convite por e-mail, utilizando atributos da tabela de códigos. Use a função if() para escolher se 'Sr.' ou 'Sra.' deve ser usado no e-mail.

A sintaxe é "if(teste,fazer_se_verdadeiro,fazer_se_falso)".

#	atributo	valor
1	Sobrenome	Smith
2	E-mail	test@test.com
3	ATTRIBUTE_2	M

Texto no convite por e-mail:

Dear {if(ATTRIBUTE_2=='M','Mr','Mrs')} {LASTNAME},

you have been invited to participate in a survey:

https:/...

Visualização do e-mail:

Exemplos de cálculo / avaliação

Calcular valores de avaliação em tempo de execução e armazenar os resultados nos dados do inquérito

Este exemplo usa todos os recursos do EM, incluindo Relevância, Personalização e o tipo de pergunta Equação.

Ele também mostra que todos eles funcionam com JavaScript. Assim, se você tiver esses recursos em uma página, ela mudará dinamicamente conforme as pessoas definem e alteram suas respostas.

#	Código	Pergunta	Tipo	Relevância
1	numKids	Quantos filhos você tem?	Entrada numérica	1
2	kid1	Qual é a idade do seu primeiro filho?	Entrada numérica	numKids >= 1
3	kid2	Qual é a idade do seu segundo filho?	Entrada numérica	numKids >= 2
4	kid3	Qual é a idade do seu terceiro filho?	Entrada numérica	numKids >= 3
5	kid4	Qual é a idade do seu quarto filho?	Entrada numérica	numKids >= 4
6	sumKidAges	{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)}	Equação	1
7	kidSummary	Você disse que tem {numKids}. {if(numKids==1,'child','children')}. {if(numKids>1,implode(' ','The sum of ages of your first ',min(numKids,4),' kids is ',sumKidAges,'.'),' ')}	Exposição do texto	1

Para baixar este exemplo, clique na seguinte hiperligação: Assessments_survey_example.

Abaixo você encontra capturas de tela de perguntas representativas. Como você pode ver, o EM destaca a sintaxe de todos os campos que podem conter personalização. Aqui, você vê exemplos de destaque de sintaxe em Relevância, no tipo de pergunta Equação e em substituições dentro de uma pergunta. Você também pode usar substituições em Ajuda, Exibição do cabeçalho do grupo, Mensagem de boas-vindas e Mensagem final.

No próximo exemplo, como a relevância é {numKids >= 2), a pergunta só ficará visível se o participante informar que tem pelo menos dois filhos.

Abaixo, você pode observar que cada variável tem o sufixo .NAOK anexado. Isso ocorre por causa da forma como o EM oferece suporte à relevância em cascata. Sem o .NAOK, a soma só seria calculada se a pessoa informasse que tem 4 filhos (ou seja, se todas as variáveis fossem relevantes). O uso do .NAOK significa que queremos calcular a soma mesmo que todas ou algumas das variáveis sejam irrelevantes (ou seja, "Não aplicável" (NA) está tudo bem (OK)).

No entanto, o atributo .NAOK afeta apenas se as variáveis são passadas para o EM. Se o participante informar inicialmente que tem 3 filhos e preencher a idade de cada um, mas depois mudar de ideia e disser que tem 2, não queremos ver a soma dos 3 valores informados, pois o terceiro filho passa a ser "não aplicável" no nosso caso:

Cada Expressão separada é destacada com um fundo bege. Como você pode ver, há três Expressões separadas aqui. A última contém uma mensagem que só é exibida, condicionalmente, se a pessoa tiver mais de um filho.

Agora, veja as capturas de tela do inquérito em funcionamento.

Quando você acessa a página pela primeira vez, vê isto. Observe que aparece "Você tem 0 filhos" em vez de "Você tem 0 filho".

Se eu alterar o valor do número de filhos para 1, a exibição muda instantaneamente para isto, mesmo estando na mesma página:

Agora observe que a gramática está correta: "Você tem 1 filho".

Agora altero o valor do número de filhos para 3, e a exibição muda instantaneamente para isto.

Observe que agora você vê a mensagem condicional na parte inferior: "A soma das idades dos seus primeiros 3 filhos é 0.".

Agora vou informar as idades dos meus filhos imaginários e obtenho esta exibição, somando as idades deles:

Novamente, a pontuação e a exibição são atualizadas instantaneamente à medida que insiro os valores, de modo que você pode usar isso para mostrar o total parcial de uma pontuação de avaliação.

Agora altero o valor do número de filhos para 2. A exibição mudou para isto:

Observe que, embora eu tenha informado o valor 5,5 para o terceiro filho, o relatório agora soma apenas os valores dos meus 2 primeiros filhos.

O motivo é que o terceiro valor agora é irrelevante, e valores irrelevantes são ativamente ignorados pelo EM.

Se eu voltasse a alterar o número de filhos para 3, veria novamente o valor 5,5 que informei. Ou seja, não perco nenhuma informação inserida na página.

No entanto, se eu navegar para a Página seguinte ou para a Página anterior, todos os valores irrelevantes serão definidos como NULL na sessão e no banco de dados. Assim, se eu mantivesse o valor em 2, fosse para a página seguinte e depois voltasse e informasse que, na verdade, tenho 3 filhos, não veria mais a idade 5,5.

Insira dados e veja um relatório que muda dinamicamente com o que foi inserido na mesma página

Este exemplo apresenta o processo de personalização (Tailoring) no LimeSurvey.

Para baixar este exemplo, clique na seguinte hiperligação: Exemplo de inquérito com alterações dinâmicas.

Veja como a página aparece inicialmente. Você vê apenas a pergunta que questiona em que cidade você mora:

Assim que você começar a inserir uma resposta, o processo de personalização também é iniciado:

Conforme você insere as respostas, a tabela na parte inferior da página é atualizada para mostrar os códigos de resposta e os valores das suas respostas.

Exemplos comuns de depuração

Instruções if() aninhadas (lógica condicional)

O EM suporta a função "if(test,do_if_true,do_if_false)" para que você possa executar lógica condicional ou personalização. Essa função pode ser aninhada para obter o equivalente a "if { } else if { } else { }". O EM avisa se os parênteses não estiverem balanceados (por exemplo, se faltar um parêntese de fechamento) ou se houver parênteses de fechamento em excesso. Ao compor instruções if aninhadas longas, procure contar os parênteses, salve, verifique se há erros de sintaxe e corrija-os, se houver. Vamos verificar juntos o exemplo abaixo.

O grupo de perguntas usado abaixo pode ser acessado aqui: Exemplo de inquérito de personalização.lsg

Primeiro, sem nada preenchido, você vê apenas "Olá."

Se você inserir um nome, a mensagem será "Olá {name}."

Se você inserir uma idade, receberá uma mensagem personalizada, dependendo de se tratar ou não de um filho em idade pré-escolar:

Idade escolar, adolescente ou adulto. Aqui está um adolescente que deseja ser anônimo:

Aqui está o arquivo de lógica do grupo. Como você pode ver na pergunta "baseada em if", há instruções if aninhadas com base na idade da pessoa.

Ao editar originalmente esta pergunta, é provável que em algum momento você use um número incorreto de parênteses. Veja o que acontece se houver parênteses a menos:

Se você passar o mouse sobre a palavra "if", que está cercada por uma caixa vermelha, será exibida a mensagem "Parentheses not balanced" (parênteses não balanceados). Neste caso, deveria haver quatro parênteses de fechamento após "already an adult!", mas há apenas três.

Se, por outro lado, houver um parêntese de fechamento a mais, ele será cercado por uma caixa vermelha, assim:

Quando você estiver de fato editando a pergunta, ela terá esta aparência: