O editor de modelos

Introdução

Um tema do inquérito controla o aspeto do seu inquérito para os participantes: o esquema da página, as cores, os tipos de letra, os logótipos e o estilo de cada pergunta. Os temas são criados com modelos Twig, CSS e JavaScript, e usam o Bootstrap 5 como framework de CSS.

Muitas alterações comuns não requerem qualquer código. O logótipo, as cores, os tipos de letra e várias definições de visualização podem ser alterados com as opções de tema. Utilize o editor de temas descrito nesta página quando quiser ir mais longe: adicionar o seu próprio CSS ou JavaScript, alterar o HTML de uma página, ou carregar imagens e outros ficheiros para o seu tema.

O LimeSurvey inclui estes temas de inquérito principais:

• Fruity TwentyThree (fruity_twentythree): O tema predefinido.
• Bootstrap Vanilla (vanilla): Um tema base simples para programadores que queiram criar o seu próprio tema baseado em Bootstrap.
• Fruity (fruity) e Bootswatch (bootswatch): Ambos expandem o Bootstrap Vanilla.

O aspeto de cada tipo de pergunta é controlado pelos temas de perguntas, e não pelo tema do inquérito. Para alterar o HTML de um tipo de pergunta, crie um tema de pergunta.

Antes de começar

Para utilizar o editor de temas, precisa da permissão global Temas (consulte permissões globais) ou tem de ser superadministrador. Expandir um tema requer o direito Criar, gravar alterações requer atualizar, e apagar um tema ou reiniciar um ficheiro requer Apagar.

  Um tema com erros pode tornar inutilizáveis todos os inquéritos que o utilizam. Teste as suas alterações com uma pré-visualização do inquérito antes de utilizar o tema num inquérito em produção.

Os temas principais não podem ser editados: expanda-os

Os temas principais são atualizados em conjunto com o LimeSurvey, pelo que não pode alterá-los diretamente. Para personalizar um, expanda o tema. Ao expandir, é criado um novo tema do utilizador que herda tudo do seu tema pai. O seu tema contém apenas os ficheiros que alterar; tudo o resto é obtido do tema pai. Desta forma, o seu tema continua a receber as correções de erros e as melhorias quando o LimeSurvey atualiza o tema pai.

Para expandir um tema, pode:

• Ir a Configuração > Temas, abrir o menu de ações (⋯) no fim da linha do tema e clicar em Expandir, ou
• Abrir o tema no editor de temas e clicar em Expandir na barra de ferramentas.

Introduza um nome para o novo tema. O editor de temas abre então o seu novo tema.

Onde os temas são guardados

• Temas principais: themes/survey/ na sua instalação do LimeSurvey.
• Temas do utilizador (temas expandidos, carregados ou importados): upload/themes/survey/.

Também pode editar os ficheiros de um tema do utilizador diretamente no servidor com o seu próprio editor. Certifique-se de que o servidor web continua a poder ler e escrever os ficheiros depois, para que possa continuar a utilizar também o editor de temas.

O editor de temas

Para abrir o editor de temas, vá a Configuração > Temas, abra o menu de ações (⋯) no fim da linha do tema e clique em Editor de temas.

Se abrir um tema principal, uma nota informa que se trata de um tema padrão e oferece uma hiperligação para o expandir. Pode ver os seus ficheiros e a pré-visualização, mas não pode gravar alterações.

Barra de ferramentas

• Exportar: Transfere o tema como um ficheiro ZIP.
• Expandir: Cria um novo tema que herda deste (consulte acima).
• Renomear: Renomeia o tema. Apenas disponível para temas do utilizador.
• Apagar: Apaga o tema. Não pode apagar o tema que está definido como tema predefinido.
• Tema: Muda o editor de temas para outro tema.
• Ecrã: Seleciona qual a página do inquérito mostrada na pré-visualização e quais os ficheiros listados para edição. Os ecrãs são: Pergunta, Lista de inquéritos, Boas-vindas, Concluído, Avaliações, Erro, Apagar tudo, Carregar, Gravar, Registo, Imprimir/Gravar as suas respostas, Estatísticas públicas, PDF, Quotas excedidas, Navegação e Participante.

Editar ficheiros

Os painéis à direita listam os ficheiros utilizados pelo ecrã selecionado:

• Ficheiros parciais de ecrã: Os modelos Twig que constroem a página.
• Ficheiros Javascript
• Ficheiros CSS
• Outros ficheiros: Imagens, tipos de letra e quaisquer outros ficheiros do tema.

Clique no nome de um ficheiro para o abrir no editor. Os ficheiros marcados como Herdado provêm do tema pai. Pode na mesma editar um ficheiro herdado: o botão por baixo do editor passa a indicar Copiar para um tema local e guardar alterações, e ao gravar o ficheiro é copiado para o seu tema com as suas alterações. A partir daí, é utilizada a sua cópia em vez do ficheiro do tema pai.

Os ficheiros que pertencem ao seu tema têm um botão Reiniciar. Reiniciar apaga a sua cópia, pelo que o ficheiro do tema pai volta a ser utilizado.

Carregar ficheiros

Utilize o campo de carregamento na parte inferior do painel Outros ficheiros para adicionar imagens, tipos de letra ou outros ficheiros ao seu tema. Os ficheiros carregados são guardados na pasta files/ do tema. Por predefinição, pode carregar imagens (gif, ico, jpg, jpeg, png) e estes tipos de ficheiro: css, js, map, json, eot, otf, ttf, woff, woff2, txt, md, xml, twig, lss, lsa, lsq e lsg. O seu administrador pode alterar estas listas com as definições allowedthemeimageformats e allowedthemeuploads em config.php.

Para mostrar uma imagem carregada num ficheiro Twig, utilize a função image():

{{ image('./files/myfile.png', 'Alternative text for the picture', {"class": "myclass"}) }}

Nos ficheiros CSS, refira-se aos ficheiros carregados com um caminho relativo à pasta css, por exemplo url('../files/background.jpg').

Pré-visualização

Por baixo do editor, uma pré-visualização mostra o ecrã selecionado com conteúdo de exemplo. Utilize os botões Dispositivos móveis, 640x480, 800x600, 1024x768 e Completo para verificar a página em diferentes tamanhos de ecrã.

A pré-visualização utiliza dados de exemplo e pode não mostrar todos os estilos exatamente como um inquérito real. Verifique sempre as suas alterações também numa pré-visualização do inquérito real.

Importar e exportar temas

• Para mover um tema para outra instalação do LimeSurvey, clique em Exportar na barra de ferramentas do editor de temas. Isto descarrega o tema como um ficheiro ZIP.
• Para instalar um tema a partir de um ficheiro ZIP, aceda a Configuração > Temas e clique em Enviar e instalar.

Como um tema é construído

Pasta do tema

A pasta de um tema contém:

• config.xml: O manifesto do tema: nome, tema pai, ficheiros CSS e JavaScript, opções de tema e os ecrãs mostrados no editor de temas.
• views/: Os modelos Twig. layout_global.twig é a disposição principal da maioria das páginas do inquérito. Outras disposições são utilizadas para páginas especiais, por exemplo layout_survey_list.twig para a lista pública de inquéritos e layout_errors.twig para as páginas de erro. A pasta views/subviews/ contém os modelos mais pequenos que as disposições incluem.
• css/ e scripts/: Os ficheiros CSS e JavaScript do tema.
• files/: Imagens e outros ficheiros utilizados pelo tema.
• options/: A página das opções de tema.

Modelos Twig

Os modelos recebem os dados do inquérito na variável aSurveyInfo. Para ver tudo o que ela contém, ative o modo debug em application/config/config.php e adicione esta linha ao fim do elemento body em layout_global.twig:

{{ dump(aSurveyInfo) }}

Para as funções que pode utilizar nos modelos, consulte Funções Twig disponíveis. Por razões de segurança, os modelos são executados numa sandbox, pelo que apenas estas funções estão disponíveis.

config.xml

A secção <files> lista os ficheiros CSS e JavaScript que são carregados nas páginas do inquérito:

• <add> adiciona um ficheiro. Se o tema pai já tiver um ficheiro com o mesmo nome, o seu ficheiro substitui-o.
• <remove> impede que um ficheiro do tema pai seja carregado.

Não precisa de listar novamente os ficheiros do tema pai: são carregados de qualquer forma.

O LimeSurvey lê o config.xml quando um tema é instalado e guarda as definições na base de dados. Depois de alterar o config.xml de um tema instalado, aceda a Configuração > Temas, abra o menu de ações (⋯) do tema e clique em Reiniciar para recarregar o ficheiro.

Adicionar o seu próprio CSS e JavaScript

Cada tema principal tem dois ficheiros reservados para o seu próprio código:

• css/custom.css: Carregado depois de todos os outros ficheiros CSS, pelo que as suas regras substituem os estilos do tema.
• scripts/custom.js: Carregado depois do JavaScript do próprio tema.

Quando expande um tema, estes são os ficheiros a alterar. Adicione o seu CSS ao custom.css em vez de editar os ficheiros CSS principais do tema, para que o seu tema continue a receber as atualizações do tema pai.

Para adicionar mais ficheiros, carregue-os e liste-os na secção <files> do config.xml do seu tema. Utilize um nome de ficheiro que não exista no tema pai, caso contrário o seu ficheiro substitui o ficheiro do pai:

<files>
    <css>
        <add>css/my-styles.css</add>
    </css>
    <js>
        <add>scripts/my-script.js</add>
    </js>
</files>

As páginas do inquérito são carregadas com Ajax por predefinição, pelo que o navegador não faz um carregamento completo da página quando um participante avança para a página seguinte. Execute o seu JavaScript tanto no primeiro carregamento da página como em cada carregamento de página por Ajax:

$(document).on('ready pjax:scriptcomplete', function () {
    // Your code here
});

Estilizar perguntas com CSS

Todos os exemplos desta secção devem ser colocados no ficheiro custom.css do seu tema.

Classes de página

Os elementos <html> e <body> têm classes que pode utilizar para estilizar páginas inteiras:

• html: O código do idioma (por exemplo en) e a direção do texto (dir-ltr ou dir-rtl).
• body: O nome do tema e de cada tema pai (por exemplo fruity_twentythree), o tipo de letra (por exemplo font-ibm-sans), o idioma (por exemplo lang-en) e brand-logo quando o logótipo é mostrado.

Classes do contentor da pergunta

Cada pergunta está envolvida num elemento com a classe question-container. Também tem:

• A classe do tipo de pergunta (consulte a tabela abaixo).
• mandatory: A pergunta é obrigatória ou obrigatória suave.
• input-error: A resposta não passou na validação, ou uma pergunta obrigatória não foi respondida.
• missing: A pergunta ainda tem partes por responder e o participante já passou por ela.
• ls-hidden e ls-irrelevant: A pergunta está oculta pela sua condição.
• ls-hidden-attribute: A pergunta está oculta pela definição "Ocultar sempre esta pergunta".
• Quaisquer classes introduzidas na definição Classe(s) CSS da pergunta (em Visualização). Utilize-a para estilizar perguntas individuais.

Por exemplo, uma pergunta Lista (Botões de opção) obrigatória que não foi respondida:

<div id="question123" class="row list-radio mandatory input-error question-container">
    ...
</div>

Classes do tipo de pergunta

Tipo de pergunta	Classe	Código do tipo
Escolher entre 5 Pontos	.choice-5-pt-radio	5
Matriz	.array-flexible-row	F
Matriz (Escolher entre 5 Pontos)	.array-5-pt	A
Matriz (Escolher entre 10 Pontos)	.array-10-pt	B
Matriz (Aumentar/Manter/Reduzir)	.array-increase-same-decrease	E
Matriz (Números)	.array-multi-flexi	:
Matriz (Textos)	.array-multi-flexi-text	;
Matriz (Sim/Incerto/Não)	.array-yes-uncertain-no	C
Matriz por coluna	.array-flexible-column	H
Matriz com duas escalas	.array-flexible-dual-scale	1
Data/Hora	.date	D
Equação	.equation	*
Submissão de ficheiro	.upload-files	|
Género	.gender	G
Texto livre muito longo	.text-huge	U
Mudança de idioma	.language	I
Lista de Seleção (Dropdown)	.list-dropdown	!
Lista (Botões de opção)	.list-radio	L
Lista com comentário	.list-with-comment	O
Texto livre longo	.text-long	T
Escolha múltipla	.multiple-opt	M
Escolha múltipla com comentários	.multiple-opt-comments	P
Entrada numérica múltipla	.numeric-multi	K
Textos curtos múltiplos	.multiple-short-txt	Q
Entrada numérica	.numeric	N
Classificação	.ranking	R
Texto livre curto	.text-short	S
Texto	.boilerplate	X
Sim/Não	.yes-no	Y

Classes para as partes de uma pergunta

Dentro do contentor da pergunta, a área de resposta utiliza estas classes. Algumas dependem das definições de visualização da pergunta: por exemplo, Matriz (Números) utiliza classes diferentes quando mostra caixas de seleção em vez de listas pendentes.

Classe	Utilizada para	Utilizada por (exemplos)
.ls-answers	O elemento que contém todas as opções de resposta	Todos os tipos de pergunta
.answers-list	Uma lista ou linha de opções de resposta	Lista (Botões de opção), Escolha múltipla, Classificação, linhas da maioria das matrizes
.subquestion-list, .questions-list	Uma lista ou tabela de perguntas secundárias	Matrizes, Textos curtos múltiplos, Entrada numérica múltipla
.answer-item	Uma opção de resposta ou campo de entrada	Quase todos os tipos de pergunta
.noanswer-item	A opção "Sem resposta"	Matrizes, Escolher entre 5 Pontos, Lista com comentário
.question-item	Uma pergunta secundária que também é uma resposta	Escolha múltipla, Textos curtos múltiplos, Entrada numérica múltipla
.radio-list	Uma lista ou linha de botões de opção	Lista (Botões de opção), Escolher entre 5 Pontos, Lista com comentário, linhas de matrizes com botões de opção
.radio-array	Uma tabela de botões de opção	Matriz, Matriz (Escolher entre 5 Pontos), Matriz (Escolher entre 10 Pontos), Matriz (Aumentar/Manter/Reduzir), Matriz (Sim/Incerto/Não)
.radio-item	Um botão de opção com a sua etiqueta	Lista (Botões de opção), Escolher entre 5 Pontos, Lista com comentário, matrizes com botões de opção
.checkbox-list	Uma lista de caixas de seleção	Escolha múltipla, Escolha múltipla com comentários
.checkbox-array	Uma tabela de caixas de seleção	Matriz (Números) com disposição de caixa de seleção
.checkbox-item	Uma caixa de seleção com a sua etiqueta	Escolha múltipla, Escolha múltipla com comentários, Matriz (Números) com disposição de caixa de seleção
.checkbox-text-item	Uma caixa de seleção com um campo de texto	Escolha múltipla com comentários
.comment-item	O campo de comentário junto a uma caixa de seleção	Escolha múltipla com comentários
.text-list	Uma lista de caixas de texto	Textos curtos múltiplos, Entrada numérica múltipla
.text-item	Uma caixa de texto	Texto livre curto, longo e muito longo, Textos curtos múltiplos, Matriz (Textos)
.number-list, .numeric-item	Campos de entrada numérica	Entrada numérica múltipla, Entrada numérica
.number-array	Uma tabela de campos de entrada numérica	Matriz (Números), Matriz (Textos)
.text-array	Uma tabela de caixas de texto	Matriz (Textos), Matriz (Números)
.dropdown-array, .dropdown-list, .dropdown-item	Tabelas, linhas e células com listas pendentes	Matriz (Números), Matriz com duas escalas com listas pendentes
.date-item	O campo de data	Data/Hora
.upload-item	A área de submissão de ficheiro	Submissão de ficheiro
.answertext	O texto da pergunta secundária numa linha de matriz	Matrizes
.col-answers	A coluna dos textos das perguntas secundárias	Matrizes
.ls-heading	A linha de cabeçalho com as opções de resposta	Matrizes
.ls-odd, .ls-even	Linhas alternadas	Matrizes
.ls-label-xs-visibility	Uma etiqueta que só é visível em ecrãs pequenos e para leitores de ecrã	Células de matrizes
.ls-input-group-extra	O prefixo ou sufixo de um campo de entrada	Texto livre curto, Entrada numérica, Textos curtos múltiplos, Entrada numérica múltipla
.ls-js-hidden	Oculto quando o JavaScript está ativo	Matriz com duas escalas, Lista (Botões de opção)
.ls-no-js-hidden	Oculto quando o JavaScript não está ativo	Classificação
.ls-js-hidden-sr	Oculto quando o JavaScript está ativo, mas ainda lido pelos leitores de ecrã	Classificação

Em Lista (Botões de opção), a opção "Sem resposta" tem a classe no-anwser-item (com esta grafia) em vez de noanswer-item.

Por exemplo, este é o HTML das respostas de uma pergunta do tipo Lista (Botões de opção):

<ul class="ls-answers answers-list radio-list list-unstyled" role="radiogroup">
    <li id="javatbdQ123_S456" class="answer-item radio-item">
        <input type="radio" value="A" name="Q123" id="answerQ123A">
        <label for="answerQ123A" class="control-label radio-label">Option A</label>
    </li>
    ...
</ul>

Classes de validação e de dicas

As dicas de validação (como "Escolha uma das seguintes respostas" ou "Introduza um número entre 1 e 10") têm sempre a classe ls-em-tip. Enquanto o participante responde, o LimeSurvey adiciona ls-em-success quando a regra da dica é cumprida e ls-em-error quando não é, para que possa estilizar os dois estados de forma diferente. As dicas escondidas com a definição Esconder sugestão da pergunta recebem a classe hide-tip.

Cada dica tem também uma classe para o seu tipo:

Classe	Dica
.em_default	A dica predefinida do tipo de pergunta (por exemplo, "Escolha uma das seguintes respostas")
.em_num_answers	Número mínimo ou máximo de respostas
.em_value_range	Valor mínimo ou máximo
.em_sum_range	Soma mínima ou máxima dos valores
.em_sum_equals	Os valores devem somar um determinado total
.em_value_integer	Apenas são permitidos números inteiros
.em_numbers_only	Apenas são permitidos números
.em_other_numbers_only	Apenas são permitidos números no campo "Outro"
.em_other_comment_mandatory	A opção "Outro" está selecionada, mas o respetivo campo de texto está vazio
.em_regex_validation	A resposta tem de corresponder ao padrão de validação
.em_q_fn_validation	A equação de validação da pergunta
.em_sq_fn_validation	A equação de validação da pergunta secundária

Idiomas da direita para a esquerda (RTL)

Para os idiomas da direita para a esquerda, o elemento <html> tem a classe dir-rtl e os temas principais carregam uma versão RTL do seu ficheiro CSS principal. Utilize .dir-rtl no seu CSS para regras que se apliquem apenas a idiomas da direita para a esquerda.

Dicas e truques

Estas receitas são colocadas em custom.css (ou num ficheiro Twig, quando indicado) de um tema que tenha estendido a partir de um tema principal. Nos exemplos, substitua #c0392b pela sua própria cor.

Alterar a cor dos botões de opção e das caixas de seleção

Para utilizar uma das cores incluídas no Fruity TwentyThree, selecione uma Cor do tema nas opções de tema. As opções de tema permitem também escolher um Verificar ícone diferente.

Para qualquer outra cor, adicione CSS ao custom.css. Os temas principais desenham os seus próprios botões de opção e caixas de seleção em vez de utilizarem os predefinidos do navegador, pelo que alterar a cor significa alterar estes elementos desenhados.

Fruity TwentyThree:

.radio-item input[type=radio]:checked + label::before,
.checkbox-item input[type=checkbox]:checked + label::before {
    border-color: #c0392b;
}
.radio-item input[type=radio]:checked + label::after {
    background-color: #c0392b;
}
.checkbox-item input[type=checkbox]:checked + label::after {
    color: #c0392b;
}
/* The text of the selected answer */
.radio-item input[type=radio]:checked + label,
.checkbox-item input[type=checkbox]:checked + label {
    color: #c0392b;
}

Bootstrap Vanilla, Fruity e Bootswatch:

.radio-item input[type=radio]:checked + label::after {
    background-color: #c0392b;
}
.checkbox-item input[type=checkbox]:checked + label::after {
    background-color: #c0392b;
    border-color: #c0392b;
    color: #ffffff;
}

Mantenha contraste suficiente entre a cor e o fundo, para que os participantes com baixa visão consigam ver quais as respostas selecionadas.

Aumentar os botões de opção e as caixas de seleção

Botões de opção e caixas de seleção maiores são mais fáceis de tocar em telemóveis e tablets. Isto funciona em todos os temas principais:

.radio-item label::before,
.radio-item label::after,
.checkbox-item label::before,
.checkbox-item label::after {
    scale: 1.3;
}

No Fruity TwentyThree, adicione também algum espaço entre os botões de opção e o texto da resposta:

.radio-item label {
    padding-left: 14px;
}

Valores até cerca de 1,4 funcionam sem outras alterações. Com valores maiores, os controlos começam a sobrepor-se ao texto da resposta e aos limites das linhas das tabelas em ecrãs pequenos, pelo que também precisa de adicionar mais espaço à sua volta.

Alterar a cor da barra de progresso

.progress-bar {
    background-color: #c0392b;
}

Mostrar conteúdo apenas num idioma

O elemento <body> tem uma classe com o idioma atual, como lang-en ou lang-fr. Pode utilizá-la para mostrar conteúdo diferente por idioma, por exemplo uma linha de ajuda no rodapé. Adicione o texto de cada idioma a um ficheiro Twig do seu tema, como subviews/footer/footer.twig:

<div class="help-fr" lang="fr">Pour de l'aide, appelez le 000000</div>
<div class="help-en" lang="en">For help, please call 000000</div>

Depois, esconda o texto dos outros idiomas em custom.css:

body:not(.lang-fr) .help-fr,
body:not(.lang-en) .help-en {
    display: none;
}

Utilizar um logotipo diferente por inquérito

Não precisa de um tema separado para cada logotipo. As opções de tema podem ser definidas para um único inquérito: abra o inquérito, clique em Opções de tema no menu Configurações do inquérito e selecione um Ficheiro do logotipo diferente. Consulte Opções de tema.

Apresentar um favicon personalizado

Um favicon é o pequeno ícone apresentado no separador do navegador e nos favoritos. Os temas principais mostram o ficheiro files/favicon.ico do tema. Para utilizar o seu próprio ícone, dê-lhe o nome favicon.ico e carregue-o no painel Outros ficheiros do seu tema estendido. Ele substitui o ícone do tema pai.

Centrar o logotipo no Fruity TwentyThree

Ative o Logotipo nas opções de tema e depois adicione isto ao custom.css:

#survey-nav .container-fluid {
    position: relative;
}
#survey-nav .logo-container {
    position: absolute;
    left: 50%;
    transform: translateX(-50%);
}

Adicionar o seu próprio logótipo à lista pública de inquéritos

Por predefinição, a lista pública de inquéritos mostra o logótipo do LimeSurvey. Para mostrar o seu próprio logótipo:

1. Expanda o Fruity TwentyThree e abra o seu tema no editor de temas.
2. Carregue o seu logótipo no painel Outros ficheiros.
3. Selecione o ecrã Lista de inquéritos e abra layout_survey_list.twig.
4. Pesquise o <div> que contém {{ include('./ls_logo_svg.twig') }}. Substitua este <div> completo, incluindo a linha include, pelo código apresentado abaixo destes passos.
5. Clique em Copiar para um tema local e guardar alterações.
6. Aceda a Configuração > Configurações globais > Geral e selecione o seu tema como Theme for public survey list and error pages.

Utilize o nome do ficheiro que carregou e o nome da sua organização como texto alternativo:

{{ image('./files/mylogo.png', 'Name of your organisation', {"class": "img-fluid mx-auto d-block"}) }}

Adicionar uma linha separadora às matrizes com duas escalas

Para desenhar uma linha vertical entre as duas escalas de uma pergunta do tipo Matriz com duas escalas:

.array-flexible-dual-scale .header_separator,
.array-flexible-dual-scale .dual_scale_separator {
    border-right: 1px solid #00a8e1;
}

JavaScript nas perguntas

Para executar JavaScript em todas as páginas dos seus inquéritos, coloque-o no ficheiro custom.js do seu tema (consulte acima).

Também pode adicionar um script ao texto de uma única pergunta ou grupo. O LimeSurvey remove os scripts destes textos, a menos que o filtro XSS esteja desativado para o seu utilizador. O filtro nunca se aplica aos superadministradores. Para os outros utilizadores, a opção Filtrar HTML por XSS tem de estar desativada em Configuração > Configurações globais > Segurança. Faça-o apenas se confiar em todos os que podem editar inquéritos. Para mais detalhes e exemplos, consulte Soluções alternativas: manipular um inquérito em tempo de execução com Javascript.