Guias práticos do ExpressionScript

Resumo do que foi explicado anteriormente

Se acompanhou até aqui a estrutura do Manual do LimeSurvey, já conhece a terminologia do LimeSurvey. Em seguida, abordámos as expressões e as variáveis, para aprender a melhorar os seus inquéritos. Na parte seguinte, passámos aos tipos e significados do realce de sintaxe, para aprender a corrigir erros de sintaxe.

Com estas noções básicas cobertas, podemos avançar para exemplos e para a explicação de como as expressões funcionam no LimeSurvey.

Realce de sintaxe

As capturas de ecrã seguintes dão exemplos, mas não mostram os valores das descrições (tooltips). Uma descrição é uma caixa informativa que é apresentada sempre que passa o rato por cima de qualquer palavra colorida a negrito.

Graças a este realce de sintaxe, é muito fácil compor expressões corretas, mesmo as mais complicadas. Embora a equipa do LimeSurvey pretenda desenvolver uma interface gráfica para construir expressões (Expression Builder), pode usar o realce de sintaxe existente para identificar e corrigir rapidamente erros de digitação. Pode também usar as descrições para validar a exatidão das suas expressões (por exemplo, confirmar que selecionou a(s) variável(eis) pretendida(s)).

Em cada um dos exemplos, existem três colunas:

1. Origem - este é o texto simples que introduziria no campo da pergunta do LimeSurvey
2. Visualização formatada - este é o equivalente, com realce de sintaxe, do que introduziu
   • Tenha em atenção que as expressões são apresentadas com um fundo bege, mas sem chavetas à volta neste realce.
   • Como o EM suporta substituição recursiva, mostrar chavetas no realce causaria erros de sintaxe
3. Resultado - este é o resultado gerado quando o EM processa a origem
   • Tudo o que pode ser substituído corretamente é substituído
   • As expressões com erros são apresentadas na própria linha, com realce de sintaxe. Os erros são rodeados por uma caixa com contorno vermelho.

Sintaxe correta

Pode encontrar abaixo exemplos de sintaxe correta:

1. Valores: mostra que as variáveis conhecidas são codificadas por cores consoante estejam ou não definidas na página atual.
2. Atributos da pergunta: mostra que a notação com ponto permite aceder a algumas propriedades das perguntas
3. Matemática: mostra que são suportados cálculos básicos e complexos
4. Processamento de texto: mostra algumas das funções de processamento de texto disponíveis
5. Datas: mostra duas das funções relacionadas com datas disponíveis
6. Condicional: mostra a utilização da função if(). As opções podem ser aninhadas.
7. Parágrafo personalizado: pode personalizar totalmente um relatório com base em valores anteriores
8. O EM processa dentro de cadeias de caracteres: mostra que consegue fazer substituições dentro de cadeias de caracteres. Este exemplo gera o nome de uma imagem personalizado.
9. O EM não processa chavetas como estas: mostra que, se as chavetas forem escapadas, ou se existir um espaço em branco entre a expressão e as chavetas, o ES ignora a expressão.

Sintaxe EM com erros

Eis exemplos de erros comuns ao escrever expressões ES. Tenha em atenção que as descrições fornecem informações adicionais.

1. JavaScript em linha em que se esqueceu de adicionar espaços após a chaveta
   • Como "document.write" aparece logo a seguir a uma chaveta, o EM pensa que se trata de uma expressão e assinala a vermelho "document" e "write", uma vez que são, respetivamente, uma variável e uma função não definidas
2. Variáveis, funções e operadores desconhecidos/com erros ortográficos
   • Aqui esquecemo-nos de que estamos a usar o nome de variável "gender" em vez de "sex", mas o EM deteta esse erro. Assinala também a vermelho '++', uma vez que não é um operador suportado.
3. Avisa se usar = em vez de eq, ou se efetuar atribuições de valores
   • Tenha em atenção que '=' e '+=' estão a vermelho em vez de preto. Se passar o rato por cima, verá avisos de que está a atribuir um valor.
4. Número de argumentos incorreto nas funções
   • if() aceita 3 argumentos, mas foram indicados 4, por isso, ao passar o rato por cima do "if" assinalado a vermelho, é explicado o erro e mostrada a sintaxe suportada
   • sum() aceita um número ilimitado de argumentos, mas existe uma vírgula a mais antes do parêntese de fecho, por isso é assinalada a vermelho
5. Parênteses desemparelhados
   • Este é um dos erros mais comuns ao escrever expressões.
   • Isto mostra dois exemplos de parênteses de fecho em falta e um exemplo de um parêntese de fecho a mais.
6. Sintaxe não suportada
   • Se usar um operador ou pontuação que o ES não suporta, será assinalado a vermelho.
7. Atribuições inválidas
   • Algumas variáveis são de leitura e escrita e os seus valores podem ser alterados. Outras são só de leitura.
   • Se tentar alterar o valor de uma variável só de leitura, não é possível. O EM assinalará a tentativa a vermelho.
   • Se tentar atribuir um valor a uma equação ou a uma cadeia de caracteres, também obterá um erro

Exemplos "em direto" de realce de sintaxe com descrições ativas

Origem	Visualização formatada	Resultado
Eis um exemplo de sintaxe correta com descrições Olá {if(gender=='M','Mr.','Mrs.')} {surname}, agora são {date('g:i a',time())}. Sabe onde estão os seus {sum(numPets,numKids)} filhos e animais de estimação?	Eis um exemplo de sintaxe correta com descrições Olá if(gender == 'M','Mr.','Mrs.') surname, agora são date('g:i a',time()). Sabe onde estão os seus sum(numPets,numKids) filhos e animais de estimação?	Eis um exemplo de sintaxe correta com descrições Olá Mr. Smith, agora são 6:07 am. Sabe onde estão os seus 3 filhos e animais de estimação?
Eis erros comuns para poder ver as descrições 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 de parâmetros incorreto: {sprintf()},{if(1,2)},{date()} Atribuição a variáveis só de leitura:{TOKEN:ATTRIBUTE_1+=10},{name='Sally'} Parênteses desemparelhados: {pow(3,4},{(pow(3,4)},{pow(3,4))}	Aqui estão alguns erros comuns para que possa ver as dicas 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 de parâmetros incorreto: sprintf(),if(1,2),date() Atribuição a variáveis só de leitura:TOKEN:ATTRIBUTE_1+=10,name='Sally' Parênteses não balanceados: pow(3,4,(pow(3,4),pow(3,4))	Aqui estão alguns erros comuns para que possa ver as dicas 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 de parâmetros incorreto: sprintf(),if(1,2),date() Atribuição a variáveis só de leitura:TOKEN:ATTRIBUTE_1+=10,name='Sally' Parênteses não balanceados: 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

"Caro {Sr.}/{Sra.} Smith..."

Utilize a função if() para escolher condicionalmente se deve ser apresentado 'Sr.' ou 'Sra.'.

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

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

Como pode observar abaixo, "Sr." e "Sra." são personalizados de acordo com a resposta que o participante seleciona na pergunta "gender".

"Caro {Sr.}/{Sra.} Smith..." no email de convite

Pode utilizar o exemplo anterior no email de convite, recorrendo aos atributos da tabela de códigos. Utilize a função if() para escolher se deve ser utilizado 'Sr.' ou 'Sra.' no email.

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

#	atributo	valor
1	Último nome	Smith
2	Endereço de email	test@test.com
3	ATTRIBUTE_2	M

Texto no email de convite:

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

you have been invited to participate in a survey:

https:/...

Vista do email:

Exemplos de cálculo / avaliação

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

Este exemplo utiliza todas as funcionalidades do EM, incluindo Relevância, Personalização e o tipo de pergunta Equação.

Mostra também que todas elas funcionam com JavaScript, pelo que, se tiver estas funcionalidades numa página, a mesma será alterada dinamicamente à medida que os participantes definem e alteram as suas respostas.

#	Código	Pergunta	Tipo	Relevância
1	numKids	Quantos filhos tem?	Entrada numérica	1
2	kid1	Que idade tem o seu primeiro filho?	Entrada numérica	numKids >= 1
3	kid2	Que idade tem o seu segundo filho?	Entrada numérica	numKids >= 2
4	kid3	Que idade tem o seu terceiro filho?	Entrada numérica	numKids >= 3
5	kid4	Que idade tem o seu quarto filho?	Entrada numérica	numKids >= 4
6	sumKidAges	{sum(kid1.NAOK,kid2.NAOK,kid3.NAOK,kid4.NAOK)}	Equação	1
7	kidSummary	Disse que tem {numKids}. {if(numKids==1,'filho','filhos')}. {if(numKids>1,implode(' ','A soma das idades dos seus primeiros ',min(numKids,4),' filhos é ',sumKidAges,'.'),' ')}	Texto	1

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

Pode encontrar abaixo capturas de ecrã de perguntas representativas. Como pode ver, o EM destaca a sintaxe de todos os campos que possam conter personalização. Aqui, pode ver exemplos de destaque de sintaxe na Relevância, no tipo de pergunta Equação e nas substituições dentro de uma pergunta. Também pode utilizar substituições na Ajuda, na apresentação do cabeçalho do grupo, na Mensagem de boas-vindas e na Mensagem final.

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

Abaixo, pode observar que cada variável tem o sufixo .NAOK anexado. Isto deve-se à forma como o EM suporta a relevância em cascata. Se não tivesse .NAOK, a soma só seria calculada se a pessoa indicasse que tem 4 filhos (ou seja, se todas as variáveis fossem relevantes). A utilização de .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á bem (OK)).

No entanto, o atributo .NAOK afeta apenas o facto de as variáveis serem ou não passadas ao EM. Se o inquirido indicar inicialmente que tem 3 filhos e introduzir as idades de cada um, mas depois mudar de ideias e indicar que tem 2, não queremos ver a soma dos 3 valores introduzidos - uma vez que, neste caso, o terceiro filho já não é "não aplicável":

Cada Expressão individual é identificada por uma cor, com um fundo bege. Como pode ver, existem três Expressões distintas neste caso. A última contém uma mensagem que só é apresentada condicionalmente, se a pessoa tiver mais do que um filho.

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

Quando visita a página pela primeira vez, vê isto. Repare que diz "You have 0 children" em vez de "You have 0 child".

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

Repare agora que a gramática está correta: "You have 1 child".

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

Repare que agora vê a mensagem condicional na parte inferior: "The sum of ages of your first 3 kids is 0.".

Agora vou introduzir as idades dos meus filhos imaginários e obtenho esta apresentação, com a soma das respetivas idades:

Mais uma vez, a pontuação e a apresentação são atualizadas instantaneamente à medida que introduzo os valores, pelo que pode utilizar esta funcionalidade para mostrar um total acumulado de uma pontuação de avaliação.

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

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

O motivo é que o 3.º valor é agora irrelevante e os 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 introduzi. Assim, não perco nenhuma informação que introduza na página.

No entanto, se navegar para a Página seguinte ou para a Página anterior, todos os valores irrelevantes serão anulados (NULL) na sessão e na base de dados. Assim, se eu mantivesse o valor em 2, avançasse para a página seguinte e depois voltasse e indicasse que afinal tenho 3 filhos, já não veria a idade de 5,5.

Introduza dados e veja um relatório dinâmico do que foi introduzido na mesma página

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

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

Eis o aspeto inicial da página. Só vê a pergunta que indica em que cidade vive:

Assim que começar a introduzir uma resposta, o processo de personalização também se inicia:

À medida que introduz respostas, a tabela no fundo da página é atualizada para mostrar os códigos das respostas e os valores das suas respostas.

Exemplos comuns de depuração

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

O EM suporta a função "if(test,do_if_true,do_if_false)" para que possa executar lógica condicional ou personalização. Esta função pode ser aninhada para obter o equivalente a "if { } else if { } else { }". O EM informa-o se os parênteses não estiverem equilibrados (por exemplo, se faltar um parêntese direito de fecho) ou se tiver parênteses direitos a mais. Deve tentar contar os parênteses ao compor instruções if aninhadas longas, guardar, verificar a existência de erros de sintaxe e corrigi-los, caso existam. Vamos analisar em conjunto o exemplo abaixo.

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

Primeiro, sem nada introduzido, vê apenas "Olá."

Se introduzir um nome, aparece "Olá {name}."

Se introduzir uma idade, obtém uma mensagem personalizada, consoante seja ou não um filho em idade pré-escolar:

Idade escolar, adolescente ou adulto. Eis um adolescente que quer ser anónimo:

Eis o ficheiro de lógica do grupo. Como pode ver na pergunta "baseada em if", existem instruções if aninhadas com base na idade da pessoa.

Quando está a editar esta pergunta pela primeira vez, é provável que, em algum momento, tenha um número errado de parênteses. Eis o que acontece se tiver parênteses a menos:

Se passar o rato sobre a palavra "if", que está rodeada por uma caixa vermelha, aparece "Parentheses not balanced". Neste caso, deveria haver quatro parênteses de fecho depois de "already an adult!", mas existem apenas três.

Se, por outro lado, tiver um parêntese direito a mais, este será rodeado por uma caixa vermelha, assim:

Quando está efetivamente a editar a pergunta, esta tem o seguinte aspeto: