This page is a translated version of the page New Template System in LS3.x and the translation is 100% complete.

Вступ

Зверніть увагу: у попередніх версіях LimeSurvey файли, що визначають, як виглядає опитування, як воно подається з погляду кольорів, шрифтів, макета та (частково) поведінки, називалися «шаблоном». Через нові підходи це тепер називається «темою», а шаблон зарезервовано для прикладів опитувань.

На цій сторінці ви дізнаєтеся, як:

Користуватися новою системою тем LimeSurvey 3.0.
Використовувати наслідування для керування власними темами.
Додати зображення до вашої теми.
Керувати параметрами теми для ваших опитувань і груп опитувань.

LimeSurvey 3 впроваджує абсолютно нову систему рушія тем, що базується на Twig 1.29 та Bootstrap і підтримує наслідування тем та параметри тем. Вона повністю усуває стару систему ключових слів для заміни. Тепер 100% HTML інтерфейсу для респондентів можна налаштувати. Наприклад, у старій системі тем існувало ключове слово {ASSESSMENTS}, яке під час виконання замінювалося HTML-кодом оцінювання. Розробник теми не мав можливості змінити цей HTML (окрім використання JavaScript). Тепер існує файл assessments.twig, який містить логіку (написану на Twig) для створення цього HTML. На цих сторінках ми пояснимо, як користуватися новим рушієм тем.

Тут ми не будемо детально описувати, як працює Twig. Це свого роду дуже спрощений PHP, який забезпечує високий рівень безпеки завдяки системі «пісочниці» (ми розглянемо це докладніше в розділі про код ядра рушія тем). Якщо ви вже знаєте PHP, вам буде надзвичайно легко його опанувати. Якщо ви не знаєте PHP, його все одно буде досить легко вивчити. Будь ласка, ознайомтеся з документацією Twig 1.X: https://twig.symfony.com/

Редагування через інтерфейс адміністратора

Список тем

На інформаційній панелі адміністратора тепер є блок для доступу до списку тем:

Список поділено на 5 стовпців:

попередній перегляд теми: це просто файл зображення з назвою «preview.png» у корені теми
«назва» теми, вказана в маніфесті (config.xml у корені теми)
опис теми: рядок, заданий у її маніфесті
тип теми: Основна тема (постачається з LimeSurvey), Тема користувача (додана в каталог завантаження), XML-тема (не завантажена в базу даних)
Розширює: якщо тема розширює іншу тему, її назва буде вказана тут
Кілька кнопок дій:
- Встановити: завантажить маніфест теми, щоб додати її до бази даних і зробити доступною для вибору на рівні опитування
- Видалити: видалить записи конфігурації теми в базі даних
- Редактор теми: перенаправить вас до редактора теми
- Параметри теми: перенесе вас до глобальної конфігурації параметрів теми

Редактор теми

Ця документація припускає, що ви вже вмієте користуватися редактором теми в попередній версії LS.

Редактор теми залишено максимально наближеним до оригінального. Тому, коли ви відкриваєте основну тему, її не можна редагувати. Але тепер замість кнопки «копіювати» є кнопка «розширити».

Тепер ви розширюєте тему — *Тепер ви **розширюєте** тему*

Короткий огляд концепції наслідування тем

У LS3 тема тепер може наслідувати іншу тему, тобто «розширювати» її. Це означає, що каталог теми буде практично порожнім і міститиме лише файли (подання, таблиці стилів, скрипти, ресурси тощо), які відрізняються від оригінальних. Так вам буде легко створити набір тем для різних користувачів, не підтримуючи велику кількість різних тем. Наприклад, ви можете мати власну тему, а потім версію для однієї компанії (з її логотипом, стилем, можливо, з посиланням на її вебсайт у нижньому колонтитулі тощо), іншу версію для іншої компанії тощо. Якщо ви потім оновите CSS або загальний макет вашої власної теми, усі теми, що наслідують її, оновляться автоматично. Зверніть увагу, що наслідування рекурсивне: тема може розширювати тему, яка розширює іншу тощо.

Це також означає, що якщо ви розширюєте одну з основних тем LimeSurvey, ви й надалі отримуватимете її оновлення.

Новинки в інтерфейсі користувача

Щоб розширити тему Monochrome з LimeSurvey, перейдіть до списку тем і натисніть кнопку «Редактор теми» для теми Monochrome. Потім натисніть «Розширити» та підтвердіть нову назву «extends_monochrome».

Якщо тепер ви перейдете до каталогу завантаження (за допомогою файлового/FTP-клієнта), то побачите, що створено новий каталог: upload/themes/extends_monochrome Він містить XML-файл і каталоги, але більшість каталогів порожні. У ньому немає ні подань, ні CSS, ні JS. Проте ви все одно можете вибрати цю тему для опитування як звичайну, і вона виглядатиме точно так само, як тема monochrome.

*Дерево теми (каталоги та файли) одразу після створення. Воно практично порожнє*

Ресурси (jpg, png тощо) з оригінальної теми копіюються під час розширення теми. Це потрібно, тому що якщо ви локально копіюєте CSS-файл з оригінальної теми, і він посилається на ці файли (наприклад, в інструкції background-image), йому потрібно буде знайти ці зображення в шляху поточної теми.

Редактор теми для теми extends_monochrome виглядає так:

Великої різниці зі старим редактором тем немає. Перелічимо основні відмінності:

Ключове слово inherited у списку файлів. Воно означає, що файлу немає в каталозі теми й буде використано файл з оригінальної теми.

Основний редактор ( редактор ACE ) показує вміст вибраного файлу. Файли містять не лише HTML, CSS чи JS, а й інструкції Twig. Ці інструкції Twig дають нам змогу перенести певну логіку в подання теми, які раніше були глибоко в ядрі, а тепер їх можна налаштовувати.

Тому тепер у випадаючому списку верхнього меню доступно більше типів екранів. Ви помітите такі сторінки, як ‘Список опитувань’, ‘Завантажити’, ‘Зберегти’, ‘Помилка’, ‘Реєстрація’, ‘Оцінювання’, ‘Роздрукувати відповіді’, яких раніше не було або які раніше фактично не можна було налаштувати.

*Тепер ви можете налаштувати всі екрани*

Посилання ‘підказка’ внизу списку файлів показує, як за допомогою Twig додати зображення до вашого HTML

Кнопка ‘Зберегти зміни’ стає кнопкою Скопіювати до локальної теми та зберегти зміни

Короткий приклад: додавання зображення

Кнопка Скопіювати до локальної теми та зберегти зміни робить саме те, що вказано: якщо ви змінете щось у файлі, а потім натиснете цю кнопку, файл буде скопійовано до теми, яку ви редагуєте, а ваші зміни збережено.
Наприклад: натисніть на файл layout_global.twig, потім безпосередньо перед блоком content ( {% block content %}) додайте текст «TEST» і натисніть кнопку. Ви побачите, що мітка файлу змінилася з «inherited» на «local», а кнопка тепер є звичайною кнопкою Зберегти зміни.

Якщо ви відкриєте файловий провідник і перейдете до каталогу upload/themes/extends_monochrome/views/, то побачите, що він містить лише один файл — layout_global.twig, і що рядок «TEST» там є.

Тепер замість того, щоб додавати довільний текст, ми додамо зображення. Якщо ви натиснете на посилання «підказка», воно підкаже:
Щоб використати зображення у файлі .twig, виконайте наведені нижче дії: {{ image('./files/myfile.png', 'alt-text for my file', {"class": "myclass"}) }}
Якщо ви прочитали документацію Twig (а на цьому етапі вам слід було це зробити), ви знаєте, що {{ function( ) }} виводить на екран результат функції. Тут функція — image( ).

Якщо вам цікаво, що вона робить, ви можете знайти її в коді тут (версія RC3): функція image() в RC3

Якщо ви не розумієте код, не хвилюйтеся: вам не потрібно знати, як він працює, а потрібно знати, навіщо і як його використовувати.

Вам слід використовувати функцію image() з двох причин:

Функція image переглядає тему, щоб знайти зображення. Якщо тема, з якою ви працюєте, розширює іншу тему, і ви копіюєте файл туди, куди локально вставили зображення, але саме зображення не скопійовано до локальної теми, функція пройде деревом наслідування тем, щоб знайти, де це зображення розташоване.
Вона використовуватиме менеджер ресурсів, тому покращить продуктивність вашої теми. Докладніше про це дивіться в документації Yii Asset Manager: http://www.yiiframework.com/wiki/148/understanding-assets/

Отже, щоб додати зображення до вашої теми:

просто завантажте його як зазвичай за допомогою засобу завантаження файлів праворуч, а потім додайте його туди, де потрібно, в будь-якому файлі twig:

{{ image('./files/myfile.png') }}

Якщо ви хочете додати альтернативний текст для зображення (для програм зчитування з екрана та перевірки HTML), додайте:

{{ image('./files/myfile.png'), ‘мій альтернативний текст’ }}

Якщо ви хочете додати атрибут class та id:

{{ image('./files/myfile.png'), ‘мій альтернативний текст’, {“class”: “a_nice_css_class”, “id”: “any_id”} }}

Деякі пункти нашого списку завдань

Дати користувачам можливість завантажувати власний файл попереднього перегляду безпосередньо з редактора
Додати кнопку для видалення локального файлу та повернення до успадкованого стану
Копіювати лише зображення, що використовуються у файлах CSS (зазначивши їх у маніфесті як файли для копіювання)
Нагадувати, яку тему розширює поточна (якщо вона розширює якусь)

Параметри теми

Ще одна новинка LS3 — сторінка параметрів теми. Як ми побачимо пізніше, автори тем можуть створювати власні параметри і навіть власну сторінку параметрів в адміністративній частині. Тут ми коротко розглянемо, як працює сторінка параметрів основних тем. Щоб отримати доступ до параметрів теми на глобальному рівні, натисніть «Параметри теми» у списку тем

Розширені параметри

Коли ви відкриваєте вкладку Параметри теми, ви можете вибрати редагування або простих параметрів, або розширених параметрів. «Розширені параметри» — це просто «голá» форма, яка надає доступ до основних полів конфігурації теми з бази даних. Щоб зрозуміти, як це працює, вам також слід ознайомитися з XML-файлом і створенням теми з нуля. Тому це досить складно і призначено для досвідчених користувачів.

Однак, якщо ви все ж бажаєте виконати редагування розширених налаштувань, натисніть на вкладку Розширені параметри

Файли CSS: файли CSS, які слід додати до шаблону;
Файли JS: файли JS, які слід додати до шаблону;
Files Print Css: файли CSS, які завантажуються під час друку шаблону;
Параметри: це поле містить параметри (та їхні значення), які слід передати у вигляд шаблону;
CssFramework Name: назва CSS-фреймворку для завантаження. Наразі доступний лише Bootstrap або жодного;
Cssframework Css: у цьому полі можна замінити основний bootstrap.css на іншу власну версію;
Cssframework Js: тут можна замінити основний файл boostrap.js на іншу власну версію;
Пакети для завантаження: за допомогою цього параметра можна завантажити деякі основні пакети ресурсів LimeSurvey.

Угорі ви побачите поле завантаження, яке дає змогу завантажити файл у каталог файлів теми. Ці параметри можна використовувати для зміни всього зовнішнього вигляду теми.

Попередження! : Не змінюйте значення, якщо не знаєте, що робите!

Прості параметри

Сторінка простих параметрів надходить із самого шаблону. Вона створюється за допомогою файлу twig і трохи JavaScript у каталозі /options теми: https://github.com/LimeSurvey/LimeSurvey/tree/develop/templates/default/options (Непрацююче посилання)

Ця сторінка може повністю відрізнятися від теми до теми, і постачальників тем наполегливо заохочують створювати власний вигляд і поведінку.

Сторінка простих параметрів просто заповнює поля форми розширених параметрів. Ви можете побачити це, увімкнувши або вимкнувши налаштування на простій сторінці, і подивившись, як відповідне поле у формі розширених параметрів змінюється відповідно. Наприклад, у простих параметрах шаблону Default, якщо ви зміните тему Bootswatch на «Darkly», а потім перейдете на вкладку розширених параметрів (навіть без збереження), ви побачите, що поле «Cssframework Css» змінилося з

{"replace": [["css/bootstrap.css","css/flatly.css"]]}
на
{"replace": [["css/bootstrap.css","css/darkly.css"]]}
Ось різні прості параметри для основних тем:

Ajax mode: чи слід завантажувати наступну сторінку через ajax (швидше) чи через перезавантаження сторінки (краще для налагодження)
Фонове зображення: якщо встановлено «Так», буде завантажено зображення pattern.png (у Master його буде замінено вибором файлу)
Box container: якщо встановлено «Ні», питання не будуть розміщені в рамці (тож можна використовувати великі масиви, ширші за екран)
Brandlogo: якщо встановлено «Ні», у верхній панелі буде показано назву опитування, інакше можна вибрати одне із зображень у каталозі файлів як логотип.
Анімувати тіло: якщо встановлено «Так», можна вибрати одну з анімацій, яка застосовується під час завантаження тіла опитування
Анімувати питання: те саме для питань
Animate alerts: те саме для сповіщень
Bootstrap theme: тут можна вибрати тему Bootstrap для завантаження. Вони походять із Bootswatch https://bootswatch.com/3/

Для анімацій використовується бібліотека animate.css: https://daneden.github.io/animate.css/ Звісно, розробник теми може додати власну бібліотеку анімацій або взагалі обійтися без неї.

Монохромні теми використовують ту саму кольорову тему Bootstrap, що й інтерфейс адміністратора. Вони не застосовують систему заміни CSS-фреймворку, а просто додають файл CSS. Це ілюструє ще один спосіб роботи з користувацькими темами для розробників тем.

Система наслідування

У попередній частині ми побачили, що тема може розширювати іншу тему. Конфігурація теми також може наслідувати конфігурацію іншої теми. Це означає, що для певної теми можна мати конфігурацію на таких рівнях:

глобальний рівень (той, який ми щойно бачили, доступний зі списку тем)
рівень групи опитування
і останній — рівень опитування.

Кожен параметр на певному рівні може наслідувати значення з вищого рівня: наслідування від групи опитування. Спершу розгляньмо рівень групи опитування.

На рівні групи опитування

Справді, ще одна чудова новинка LS3 — система груп опитування. Тепер ви можете створювати різні групи для впорядкування опитувань. Щоб отримати до неї доступ, перейдіть до списку опитувань, а потім натисніть вкладку груп опитування:

У цьому списку є дві кнопки дій. Якщо група порожня, її можна видалити. В іншому випадку її завжди можна редагувати. Натиснувши кнопку редагування, ви перейдете на сторінку налаштування групи опитування:

*Редагування групи опитування за замовчуванням*

Третя вкладка цієї сторінки має назву «Параметри шаблону для цієї групи опитування». Якщо натиснути на неї, ви побачите той самий список тем, що й у списку тем, але тут доступна лише кнопка параметрів (редактор теми доступний лише з основного списку).
Тепер, якщо натиснути параметри для шаблону за замовчуванням, ви побачите таке:

Успадковувати все означає, що вся конфігурація буде успадкована з глобального рівня.
Якщо перейти на сторінку розширених параметрів, ви побачите, що для всіх полів встановлено наслідування.
Якщо натиснути «Ні» для «Успадковувати все» у простих параметрах, ви знову побачите сторінку, дуже схожу на сторінку глобальних параметрів. Єдина відмінність у тому, що для кожного поля можна встановити «Так», «Ні» або «Наслідувати»; а кожен випадаючий список має значення Наслідувати'.

Група опитування може бути дочірньою щодо іншої групи. У такому разі вона наслідуватиме параметри від батьківської групи.

На рівні опитування

Під час редагування опитування в меню на лівій панелі ви побачите новий пункт «Параметри теми». Він веде на сторінку параметрів теми, вибраної для поточного опитування. Ви знайдете ту саму систему наслідування, що й у групі опитування, але цього разу наслідування означає, що параметр буде успадкований від групи опитування, до якої належить опитування.

Приклад використання

Припустімо, ви використовуєте одну тему для різних компаній (A і B). Ви задаєте улюблені параметри на глобальному рівні (наприклад: ajax увімкнено, анімація тіла — виїжджання, сповіщення — пульсація). Потім створюєте групу опитування для кожної компанії: групу опитування для компанії A, яка міститиме всі опитування цієї компанії, та групу для компанії B, яка міститиме всі опитування компанії B. На цьому рівні ви задаєте лише логотип і фон, а решту параметрів залишаєте наслідуваними. Тож усі опитування групи A використовуватимуть логотип компанії A, а всі опитування групи B — логотип компанії B. Для одного з опитувань компанії A можна використати інший фон відповідно до теми опитування: просто змініть фон у параметрах на рівні опитування. Якщо хтось у компанії B скаже, що пульсуюче сповіщення надто агресивне і він віддав би перевагу чомусь м’якшому, наприклад плавному появленню, ви просто змінюєте анімацію сповіщення на рівні групи опитування B, і всі опитування цієї групи використовуватимуть цю анімацію. Якщо компанія A змінить свій логотип, ви можете змінити його на рівні групи опитування A, і всі опитування цієї групи використовуватимуть новий логотип.

Ці приклади базуються на поточних параметрах основної теми. Але, звісно, якщо ви розробник тем або вмієте трохи програмувати на twig, ви можете додати власні параметри. Наприклад, можна додати параметр «info footer», у якому можна вказати такі дані, як сайт компанії або телефон для довідки. Тоді, якщо в компанії A є різні відділи з різними номерами телефонів, ви можете просто створити по одній підгрупі для кожного відділу в групі опитування A. Кожна підгрупа матиме у цих параметрах власний номер телефону.

Поширені запитання щодо налаштування тем

Тут ви знайдете відповіді на запитання, які ставили на форумі і які можуть допомогти вам налаштувати вашу тему.

Налаштування CSS/JS: робота з менеджером ресурсів («чому мої зміни не застосовуються?»)

Якщо ви намагаєтеся оновити CSS/JS теми, безпосередньо редагуючи код у вашому улюбленому редакторі, ви можете здивуватися, що ваші зміни не застосовуються.

Починаючи з версії 2.50, LimeSurvey використовує менеджер ресурсів Yii: Документація Yii про ресурси

Він переміщує файли CSS/JS теми до підкаталогу tmp/ з випадковим рядком (наприклад: "tmp/1ef64ml/"). Тож якщо ви змінюєте файл css/js і повідомляєте про це менеджер ресурсів, файли копіюються до нового підкаталогу з новою назвою, щоб кеш браузера користувача оновився і він побачив новий css/js. Інакше їм довелося б очищати кеш браузера.

Ось посилання на CSS у заголовку, коли менеджер ресурсів увімкнено:

Як бачите, усі вони вказують на підпапки tmp/.

Ось посилання на CSS у заголовку, коли менеджер ресурсів вимкнено:

Як бачите, вони вказують на реальні файли теми.

Звісно, якщо менеджер ресурсів не знає, що ви змінили файл, старий файл у старому каталозі tmp/ залишиться без змін, і ваші зміни ніколи не будуть застосовані.

Отже, під час редагування CSS/JS теми у вас є кілька можливостей:

Ви можете скористатися редактором теми LimeSurvey: він працює з менеджером ресурсів, і вам не потрібно ні про що турбуватися
Ви можете увімкнути режим налагодження: це вимкне менеджер ресурсів, тож будуть викликані реальні файли css/js ваших тем (але тоді доведеться оновлювати кеш браузера під час кожного завантаження)
Ви можете оновити кеш ресурсів: у Загальні налаштування -> General -> Clear asset cache

Використання редактора теми для редагування власного CSS — це безумовно найкраще рішення.

Використання редактора теми допоможе вам зрозуміти архітектуру нового рушія тем. Також, якщо ви налаштовуєте fruity, будьте уважні зі специфічністю CSS: більшість визначень використовують селектор ".fruity" (один із класів елемента body).

Додавання власних шрифтів до моєї теми

Простий спосіб: використання Google Font CDN

Тема опитування Bootswatch використовує Google Font CDN. Подивімося, як це працює: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/bootswatch/css/variations/flatly.min.css

@import url("https://fonts.googleapis.com/css?family=Lato:400,700,400italic");

Далі шрифт Lato використовується через правила CSS: https://github.com/thomaspark/bootswatch/blob/master/dist/flatly/bootstrap.css#L72

body {
  ...
 font-family: "Lato";
 ...
}

Таким чином ви можете використовувати будь-який шрифт Google у своїй власній темі. Звісно, слід видалити вибір шрифту з параметрів вашої теми. Видаліть ці рядки в options.twig: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.twig#L209-L230

Використання локального шрифту

Звісно, ви також можете завантажити файли шрифтів і використовувати їх із локального сервера, а не з Google CDN (краще для конфіденційності). Як приклад, ось наша локальна версія шрифту noto: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/assets/fonts/noto.css

@font-face {
  font-family: 'Noto Sans';
  font-weight: 300;
  font-style: normal;
  src: url('./font-src/Noto/NotoSans-Regular.ttf');
}
...

Ви можете використати дуже схоже визначення у файлі css вашої теми, а потім скопіювати файл NotoSans-Regular.ttf до папки css/font-src/ вашої теми.

Потім застосуйте цей шрифт до body (або будь-якого іншого елемента), як вище, і видаліть вибір шрифту в параметрах за замовчуванням.

Створення власного вибору шрифту в параметрах

Наразі ви не можете легко використати вбудований вибір шрифту, щоб додати власний шрифт у параметри. Спочатку потрібно надати кінцевому користувачу можливість завантажувати власні пакети (див. наступний розділ: A look into the Fruity Font Selector )
Ось як діяти:

Додайте два шрифти (my_custom_font і my_custom_other_font) до своєї теми, використовуючи CDN або локальний сервер
Потім у своєму css-файлі додайте два нові класи:

.font-my_custom_font {
 font-family: 'my_custom_font ';
}
.font-my_custom_other_font {
 font-family: 'my_custom_other_font';
}

У XML-файлі вашої теми додайте параметр шрифту (типовим буде my_custom_font) :

    <options>
        ....
        <font>my_custom_font</font>
    </options>

у option.twig додайте свій вибір шрифту, вставивши ці рядки (поки не перевірено, тож якщо не працює, напишіть про це на форумі):

            
            <div class='row ls-space margin top-15 bottom-15 action_hide_on_inherit'>
                <hr/>
            </div>
            <div class='row action_hide_on_inherit'>
                <div class='col-sm-12'>
                    <div class='panel panel-default'>
                        <div class='panel-heading'>{{ "My custom fonts" | t }}</div>
                        <div class='panel-body'>
                            <div class='form-group row'>
                                <label for='simple_edit_font' class='control-label'>{{ "Select font:" | t }}</label>
                                <div class='col-sm-12'>
                                    <select class='form-control selector_option_value_field' id='simple_edit_font' name='font'>
                                    {% if templateConfiguration.sid is not empty or templateConfiguration.gsid is not empty %} //Shouldn't this be "theme" in stead of "template"?
                                        {% set fontOptions = fontOptions ~ '<option value = "inherit" > Inherit</option>' %}
                                    {% endif %}
                                   <optgroup  label="{{ "My Custom fonts" | t }}">
                                   <option class="font-my_custom_font"     value="custom_font"   data-font-package=""  >Custom</option>
                                  <option class="font-my_custom_other_font" value="my_custom_other_font" data-font-package=""  >Other</option>
                                  </optgroup>
                                   
                                    </select>
                                </div>
                            </div>
                        </div>
                    </div>
                </div>
            </div>

Тепер ваші користувачі зможуть обирати між цими двома шрифтами.

A look into the Fruity Font Selector

У майбутньому ми надамо кінцевому користувачу можливість завантажувати власні пакети ресурсів, зокрема пакети шрифтів. Це значно спростить налаштування шрифтів.
Щоб зрозуміти пакети Yii:
http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

Пакети LimeSurvey визначені в різних файлах. Пакети шрифтів визначені тут: https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php
Наприклад, пакет шрифту Noto визначений тут: https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/application/config/fonts.php#L47-L53

    'font-noto' => array(
        'devBaseUrl' => 'assets/fonts/',
        'basePath' => 'fonts',
        'css' => array(
            'noto.css',
        ),
    ),

Файл noto.css, який він містить, знаходиться тут: https://github.com/LimeSurvey/LimeSurvey/blob/4c40b61afb0dba8fd80154b50f5831045df8d814/assets/fonts/noto.css
Зверніть увагу на визначення css-класу ".font-noto" наприкінці файлу:

@font-face {
  font-family: 'Noto Sans';
  ...
}
...
.font-noto{
    font-family: 'Noto Sans';
}

Потім у темі Vanilla шрифт Noto використовується шляхом додавання пакета noto і встановлення для параметра шрифту значення noto:
https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L79

        <packages>
             ....
            <add>font-noto</add>
        </packages>

https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/config.xml#L58

    <options>
        ....
        <font>noto</font>
    </options>

Потім клас шрифту для body визначається за цим значенням: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/views/layout_global.twig#L76

<body class=" ...  font-{{  aSurveyInfo.options.font }} ... " ... >

Звісно, XML-файл містить лише типові значення конфігурації вашої теми. Насправді ці значення визначаються та зчитуються з бази даних (таблиця "template_configuration" (Питання: "template_" чи "theme_"?) у вигляді рядків json. Файл option.js просто використовує значення вибору шрифту з простих параметрів, щоб змінити значення у формі на вкладці розширених параметрів: https://github.com/LimeSurvey/LimeSurvey/blob/70a1d99cd2ebe411597231a8bc746b4ca9e19584/themes/survey/vanilla/options/options.js#L148-L174

Тож коли з’явиться функція «завантаження пакета ресурсів», буде легко додати скрипт, який скануватиме всі наявні пакети шрифтів і додаватиме їх до списку вибору.

Додавання параметрів теми для керування розташуванням і відображенням елементів опитування

Цей посібник показує, як додати до розширеної теми параметри для відображення елементів опитування в різних місцях. У цьому випадку ми створимо параметри теми, щоб показувати назву опитування у двох різних місцях.

Для простоти ми базуватимемо посібник на розширенні теми "bootswatch" у LimeSurvey версії 3.4.3.

Створення власної теми

Розширте тему "bootswatch", як описано вище.
Скопіюйте custom.css до локальної теми, як описано вище.

Створення нових параметрів теми

Скопіюйте вміст /themes/survey/bootswatch/options/ до /upload/themes/survey/yourThemeName/options/.

Відкрийте /upload/themes/survey/yourThemeName/options/options.twig у редакторі та знайдіть "{# Bootstrap Bootswatch theme #}". Безпосередньо перед його батьківським елементом <div class='row'> додайте це:

		{# Custom survey name in navbar #}
		<div class='row'>
			<div class='col-sm-12 col-md-6'>

				<div class='form-group row'>
					<label for='simple_edit_options_surveyname1' class='control-label'>Survey name in navbar</label>
					<div class='col-sm-12'>
						<div class="btn-group" data-toggle="buttons">
							<label class="btn btn-default">
								<input name='surveyname1' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
								Yes
							</label>
							<label class="btn btn-default">
								<input name='surveyname1' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname1'/>
								No
							</label>
						</div>
					</div>
				</div>
			</div>
		</div>
		<div class='row'>
			<hr/>
		</div>

		{# Custom survey name below progress bar #}
		<div class='row'>
			<div class='col-sm-12 col-md-6'>

				<div class='form-group row'>
					<label for='simple_edit_options_surveyname2' class='control-label'>Survey name below progress bar</label>
					<div class='col-sm-12'>
						<div class="btn-group" data-toggle="buttons">
							<label class="btn btn-default">
								<input name='surveyname2' type='radio' value='on' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
								Yes
							</label>
							<label class="btn btn-default">
								<input name='surveyname2' type='radio' value='off' class='selector_option_radio_field ' data-id='simple_edit_options_surveyname2'/>
								No
							</label>
						</div>
					</div>
				</div>
			</div>
		</div>
		<div class='row'>
			<hr/>
		</div>

Відкрийте /upload/themes/survey/yourThemeName/config.xml і додайте два елементи до блоку "options", щоб він виглядав так:

    <options>
        <ajaxmode>on</ajaxmode>
        ...
        <surveyname1>on</surveyname1>
        <surveyname2>on</surveyname2>
    </options>

Тепер на екрані Параметри теми мають з’явитися два нові параметри, як на зображенні:

Змінений вигляд для назви опитування в навігаційній панелі

Створіть новий каталог /upload/themes/survey/yourThemeName/views/subviews/header/.
Скопіюйте /themes/survey/vanilla/views/subviews/header/nav_bar.twig до цього нового каталогу.

Відкрийте /themes/survey/vanilla/views/subviews/header/nav_bar.twig і знайдіть "{# Logo option #}". Нижче змініть оператор IF для логотипу/назви опитування так, щоб він виглядав таким чином:

		{# Logo option #}
        {% if( aSurveyInfo.options.brandlogo == "on") %}
            <div class="{{ aSurveyInfo.class.navbarbrand }} logo-container"  {{ aSurveyInfo.attr.navbarbrand }}  >
                {{ image(aSurveyInfo.options.brandlogofile, aSurveyInfo.name, {"class": "logo img-responsive"}) }}
            </div>
        {% endif %}
        {% if( aSurveyInfo.options.surveyname1 == "on") %}
            <div class="{{ aSurveyInfo.class.navbarbrand }}"  {{ aSurveyInfo.attr.navbarbrand }} >
                {{ aSurveyInfo.name }}
            </div>
        {% endif %}

Додайте щось подібне до /upload/themes/survey/yourThemeName/css/custom.css:
```
.navbar-brand {
    line-height: 60px;
    font-size: 32px;
}
```
Увімкніть параметр теми "Survey name in navbar" у значення "Так"
Ви маєте побачити таке:

Змінений вигляд для назви опитування під індикатором прогресу

Створіть новий каталог /upload/themes/survey/yourThemeName/views/subviews/survey/group_subviews.
Скопіюйте /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig до цього нового каталогу.

Відкрийте /themes/survey/vanilla/views/subviews/survey/group_subviews/group_container.twig і додайте елемент <h1> для назви опитування. Він має виглядати так:

<div class="{{ aSurveyInfo.class.groupcontainer }} space-col" {{ aSurveyInfo.attr.groupcontainer }}>
 
    {# Custom survey name #}
    {% if( aSurveyInfo.options.surveyname2 == "on") %}
    	<h1 class="custom-survey-name">{{ aSurveyInfo.name }}</h1>
    {% endif %}
 
    {# Group Name #}
    {{ include('./subviews/survey/group_subviews/group_name.twig') }}
 
    {# Group Description #}
    {{ include('./subviews/survey/group_subviews/group_desc.twig') }}
 
    {#
        PRESENT THE QUESTIONS
 
        This is the main part. It will render each question for this group
     #}
 
    <!-- PRESENT THE QUESTIONS -->
    {% for  aQuestion in aGroup.aQuestions %}
         {{ include('./subviews/survey/question_container.twig') }}
    {% endfor %}
 
    <!-- Hidden inputs -->
    {% if aGroup.show_last_group == true %}
        <input type='hidden' name='lastgroup' value='{{ aGroup.lastgroup }}' id='lastgroup' />
    {% endif %}
 
    {% if aGroup.show_last_answer == true %}
        <input type='hidden' name='lastanswer' value='{{ aGroup.lastanswer }}' id='lastanswer' />
    {% endif %}
</div>

Додайте щось подібне до /upload/themes/survey/yourThemeName/css/custom.css:

.navbar-brand {
    line-height: 60ph1.custom-survey-name {
	margin: 0;
	text-align: center;
}

Увімкніть параметр теми "Survey name below progress bar" у значення "Так"
Ви маєте побачити таке:

Завантаження

Приклад розширеної теми: Media:Test_survey_names.zip

Створення теми з нуля

Документація незабаром з’явиться.

Поки що наведемо кілька порад.

Структура теми

Файли та каталоги

Коли ви створюєте тему з нуля, вам не потрібно дотримуватися структури файлів/каталогів/css/js з Vanilla. Обов’язкові css/js додаються ядром (за потреби їх можна видалити).

Єдині файли, які обов’язково має містити ваша тема, — це файли макета:

layout_global.twig : відображає сторінки для проходження опитування
layout_survey_list.twig : відображає список опитувань (якщо цю тему встановлено за замовчуванням)
layout_errors.twig : використовується для відображення помилок, що блокують показ опитування (неправильний ID опитування, порожня група в попередньому перегляді групи тощо)
layout_user_forms.twig: відображає форми користувача, наприклад: токен (учасник опитування) та реєстрація.
layout_print.twig : використовується для друку опитування в PDF
layout_printanswers.twig: друк відповідей

Вміст цих файлів і те, які файли вони підключають, повністю залежить від вас. Усі інші файли та каталоги, які ви бачите у Vanilla, є цілком необов’язковими — організуйте свій код так, як вам зручно.

Якщо ви прочитаєте код відображення фронтенду, то побачите, що назви цих файлів прямо вказані в ньому. Саме тому вони обов’язкові.

Напр.: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/helpers/SurveyRuntimeHelper.php#L462

Вміст

У файлі layout_global.twig теми Vanilla ви побачите, що ми використовуємо змінну "include_content", щоб вирішити, що показувати https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/layout_global.twig#L114-L115

                    {% set sViewContent =  './subviews/content/' ~ aSurveyInfo.include_content ~ '.twig' %}
                    {% include './subviews/content/outerframe.twig' with {'include_content': sViewContent } %}

aSurveyInfo.include_content вказує, яка дія виконується зараз: показ питань? показ результату надсилання? показ «Очистити все»? тощо. Як бачите, у vanilla ми створюємо один файл для підключення на кожну дію. Тому, якщо ви хочете дізнатися список дій, просто перегляньте каталог vanilla views/subviews/content і відкиньте розширення "twig": https://github.com/LimeSurvey/LimeSurvey/tree/2398dda3b425da1a37d4611cd7963d39ac739987/themes/survey/vanilla/views/subviews/content

clearall.twig
firstpage.twig
load.twig
mainrow.twig
main.twig
optin.twig
optout.twig
outerframe.twig
printanswers.twig
quotas.twig
register.twig
save.twig
submit_preview.twig
submit.twig
userforms.twig

Якщо ви вже створювали тему для версій LimeSurvey 2.x, то помітите, що більшість із цих файлів відповідає старим файлам pstpl з LimeSurvey 2.x. Знову ж таки, ви не зобов’язані створювати у своїй темі ці файли з такими назвами в цьому каталозі. Наприклад, ви можете просто додати в layout_global.twig величезний switch з потрібним HTML для кожної дії.

Маніфест config.xml

Маніфест теми містить основну інформацію про вашу тему. Коли ви встановлюєте тему, вміст маніфесту завантажується до бази даних у дві різні таблиці: template і template_configuration. Тому щоразу, коли ви змінюєте маніфест теми, потрібно видалити та знову встановити її (або просто скинути). Оскільки під час розробки теми цей процес дратує, ви можете примусово використовувати безпосередньо XML-файл замість записів у БД. Для цього в config.php увімкніть режим налагодження та встановіть 'force_xmlsettings_for_survey_rendering' у true.

Розділ метаданих

Нічого складного: лише основна інформація про вашу тему. Вона буде записана в таблицю templates_configuration

    <metadata>
        <name>the_name_of_your_theme</name>
        <title>The Title of your theme</title>
        <creationDate>16/10/2017</creationDate>
        <author>Your Name</author>
        <authorEmail>your@email.org</authorEmail>
        <authorUrl>http://www.yourwebsite.org</authorUrl>
        <copyright>Your Copyright </copyright>
        <license>Licence of your theme</license>
        <version>version of your theme</version>
        <apiVersion>3</apiVersion>
        <description>Description of your theme</description>
        <extends>parent_theme</extends>
    </metadata>

Кілька зауважень:

name: використовується як ключ у БД. Тому він має бути унікальним і не містити спеціальних символів (без пробілів). Зверніть увагу, що регістр не враховується
Title: використовується для відображення назви вашої теми в різних списках. Може містити спеціальні символи
description: використовується в основному списку тем опитувань. Може містити спеціальні символи і навіть HTML-код за допомогою
extends: необов’язковий, визначає батьківські теми. Тож якщо якогось файлу немає в цій темі (twig/js/css/jpg тощо), він шукатиметься в батьківській темі

Якщо ви розширили одну з 3 основних тем (Vanilla, Bootswatch, Fruity), ви можете змінити значення "extends" з однієї батьківської теми на іншу. Звісно, тему потрібно буде скинути.

Розділ файлів

Це важливий розділ. Він записується в таблицю template_configuration, у поля files_css, files_js, files_print_css як масиви JSON.

Напр.: розділ файлів теми Material Premium:

    <files>
        <css>
            <add>css/bootstrap-material-design.css</add>
            <add>css/ripples.min.css</add>
            <replace>css/ajaxify.css</replace>
            <replace>css/theme.css</replace>
            <replace>css/custom.css</replace>
            <remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>
        </css>
        <js>
            <replace>scripts/theme.js</replace>
            <replace>scripts/ajaxify.js</replace>
            <add>scripts/material.js</add>
            <add>scripts/ripples.min.js</add>
            <replace>scripts/custom.js</replace>
        </js>
        <print_css>
            <add>css/print_theme.css</add>
        </print_css>
    </files>

Усі файли CSS/JS, наявні в цьому розділі, завантажуються під час запуску опитування (в режимі ajax. Якщо режим ajax вимкнено, то, звісно, усі файли перезавантажуються на кожній сторінці).

Вони додаються до пакета ресурсів Yii (Asset Packet) на основі назви теми. Тож коли менеджер ресурсів увімкнено (режим налагодження вимкнено), ці файли копіюються до каталогу tmp разом з рештою теми (тому ви можете використовувати відносні шляхи в CSS і JS для доступу до файлів зображень). Про менеджер ресурсів у Yii: https://www.yiiframework.com/wiki/148/understanding-assets Про пакети в Yii: http://www.yiiframework.com/doc/api/1.1/CClientScript#packages-detail

Вони використовують систему успадкування. Це означає, що якщо ви додаєте файл CSS/JS до теми, але його немає в цій темі, рушій шукатиме його в усіх батьківських темах цієї теми та використає перший знайдений. Тож якщо користувач розширює вашу тему через редактор теми, усі ці файли будуть успадковані в його темі. Ключові слова стосуються цієї системи успадкування.

add : додасть файл до теми та до всіх її дочірніх тем
replace: замінить файл батьківської теми
remove: видалить файл з будь-якого пакета, навіть з основного пакета (починаючи з 3.14)

Пам’ятайте, що в config.php можна встановити 'force_xmlsettings_for_survey_rendering', щоб конфігурація зчитувалася з XML замість БД (скидання не потрібне). Це полегшить тестування змін у XML-файлах і позбавить вас від необхідності видаляти/встановлювати тему заново після кожної зміни XML.

Кілька зауважень щодо цих ключових слів:

Поради щодо наслідування

Як пояснювалося раніше, ключове слово "add" може посилатися на файл, який міститься в одній з батьківських тем. Тож ви можете «додати» файл у цьому розділі, не маючи цього файлу у вашій темі, а лише в одній з її батьківських тем. Рушій перегляне всі батьківські теми та використає перший знайдений файл. Якщо файл не знайдено, у config увімкнено режим налагодження, а в глобальних налаштуваннях увімкнено режим налагодження JS для фронтенду, у консолі з'явиться попередження. Наприклад, якщо в my_theme ми додамо: <add>css/unexisting.css</add>, у консолі ми побачимо:

 (¯`·._.·(¯`·._.· Theme Configuration Error  ·._.·´¯)·._.·´¯) 

Can't find file 'css/unexisting.css' defined in theme 'my_theme'

Якщо режим налагодження вимкнено, помилок не буде показано взагалі. Рушій просто проігнорує хибні інструкції add.

Коли використовувати add, коли replace, а коли можна залишити все батьківській темі?

По-перше: add і replace — це по суті одне й те саме ключове слово. Можна використовувати будь-яке з них, рушій діятиме однаково. Вони розрізняються лише для людей, щоб було зрозуміло ваш намір.

Ви не можете додати файл з такою самою назвою, як у батьківської теми: він завжди її замінить. Наприклад: якщо є файл "my_mother_theme/foo.css" і ви додаєте файл "foo.css" у дочірній темі, до теми буде додано лише "daughter_theme/foo.css". Якщо ви хочете зберегти "my_mother_theme/foo.css", просто виберіть іншу назву для "daughter_theme/foo.css", наприклад "daughter_theme/bar.css". Отже, ключове слово "add" можна використовувати як "replace".

Якщо вам цікаво чому: це значно спрощує автоматичне створення наслідуваної теми — копіювання розділу файлів працює одразу (не потрібно перейменовувати "add" на "replace" під час розширення файлу).

Щоб було зрозуміліше, розгляньмо приклад Fruity. Ось його розділ файлів CSS:

        <css>
            <add>css/variations/sea_green.css</add>
            <replace>css/animate.css</replace>
            <replace>css/theme.css</replace>
            <replace>css/custom.css</replace>
        </css>

Якщо ви подивитеся на файл custom.css у fruity, він точно такий самий, як і у vanilla. Ми могли б видалити файл custom.css у fruity, і було б завантажено файл з vanilla. Ми могли б видалити інструкцію <replace>custom.css</replace> з маніфесту Fruity, тоді було б використано інструкцію з vanilla, а також завантажено custom.css з vanilla.

То чому ж ми використовуємо інструкцію <replace>custom.css</replace> у маніфесті fruity? Відповідь проста: тому що ми хочемо, щоб кінцевий користувач міг розширити тему fruity, змінити файл у своїй локальній темі та завантажувати цей змінений файл зі своєї наслідуваної теми. Щоб це зрозуміти, просто розширте fruity і погляньте на розширену тему. У розширеній темі навіть немає файлу custom.css, тож буде використано файл з fruity. Але якщо користувач створить цей файл у розширеній темі (натиснувши «Розширити» в редакторі теми), цей файл буде завантажено з його теми.

Отже, загалом: якщо ви створюєте тему з нуля, не розширюючи жодної теми, просто використовуйте інструкцію add, щоб додати ваші файли CSS/JS. Легко й просто. якщо ви створюєте тему, що розширює іншу тему, і не хочете, щоб користувачі могли розширювати файл CSS/JS з батьківської теми: не використовуйте інструкцію add у своєму маніфесті. Файли все одно завантажуватимуться з конфігурації батьківської теми. якщо ви створюєте тему, що розширює іншу тему, і хочете замінити файл з батьківської теми: використовуйте ключове слово replace (ключове слово add дасть той самий результат). якщо ви створюєте тему, що розширює іншу тему, не замінюєте певний файл CSS/JS, але хочете, щоб користувачі могли розширювати цей файл: тоді використовуйте інструкцію «replace» у своєму маніфесті для цього файлу. Навіть якщо ви не замінюєте файл, використання ключового слова replace у маніфесті дозволяє користувачеві зробити це, якщо він забажає.

Лише останній випадок потребує трохи розумової гімнастики, щоб його зрозуміти; усі інші випадки тривіальні.

Ви також можете реєструвати файли CSS і JS безпосередньо з коду twig. Ці файли буде завантажено лише тоді, коли викликається файл twig. Якщо ви хочете, щоб користувачі могли наслідувати ці файли JS/CSS із редактора теми, не забудьте використовувати функції Template:RegisterTemplateCssFile('my style.css') і Template:RegisterTemplateScript('my script.js'). Якщо ви не використовуєте ці функції, ваша тема може працювати, але наслідування для неї буде порушено. Це та сама логіка, що й у функції Template:Image('my picture.jpg')

Ключове слово remove

Ключове слово remove доступне лише починаючи з версії 3.14. З його допомогою можна видалити будь-який файл CSS/JS з будь-якого пакета, навіть із основних. Воно використовується в темі Material Premium, щоб видалити файли Awesome Bootstrap Checkbox:

<remove>awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css</remove>

тому слід використовувати точно такий самий запис, як і в файлі пакета (наприклад, "awesome-bootstrap-checkbox.css" без шляху до папки не спрацює). Повний список основних пакетів та їхніх файлів ви знайдете в /application/config/packages.php і config/third_party.php. Наприклад, для awesome-bootstrap-checkbox.css: https://github.com/LimeSurvey/LimeSurvey/blob/2398dda3b425da1a37d4611cd7963d39ac739987/application/config/packages.php#L54-L56

        'css'=> array(
            'awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css',
        ),

Ще один спосіб дізнатися точну назву для тегу remove — увімкнути менеджер ресурсів (вимкнувши режим налагодження або встановивши 'use_asset_manager'=>true у конфігурації). Тоді шлях, який потрібно використовувати, — це шлях одразу після випадкової директорії в директорії tmp. Наприклад, для awesome-bootstrap-checkbox.css:

<link rel="stylesheet" type="text/css" href="/tmp/assets/cbc4e3cb/awesome-bootstrap-checkbox/awesome-bootstrap-checkbox.css" />

Файли, які не слід видаляти:

jquery-3.1.1.min.js : потрібен

jquery-migrate-3.0.0.min.js : потрібен

survey.js : потрібен

moment-with-locales.min.js : потрібен для типу питання «Дата» (і, схоже, ще для деяких)

em_javascript.js : потрібен для всього JavaScript ExpressionScript

Розділ параметрів

Цей розділ стосується параметрів вашої теми. Він використовується для заповнення поля "options" таблиці template_configuration у вигляді масиву JSON.

Додаткова інформація

Theme:Available function

Деякі примітки

ПРИМІТКА: якщо ви редагуєте XML-файл теми, потрібно видалити та знову встановити тему, щоб зміни було враховано.

ПРИМІТКА: щоб уникнути цього, ви можете примусово використовувати XML замість бази даних. У config.php увімкніть режим налагодження та розкоментуйте:

'force_xmlsettings_for_survey_rendering' => true, // Розкоментуйте, якщо хочете примусово використовувати XML-файл замість бази даних (для зручної розробки теми)

Будьте обережні: усе буде завантажуватися з XML (зокрема параметри тощо)

ПРИМІТКА: якщо ви редагуєте файли CSS/JS вручну (не використовуючи Редактор теми) і режим налагодження вимкнено, тепер можна примусово очистити ресурси (assets). У розділі «Загальні налаштування» на вкладці «Загальні» натисніть кнопку «Очистити кеш ресурсів».

ПРИМІТКА: якщо ви видалите розділ

Основні розділи

Нова система шаблонів у LS3.x

From LimeSurvey Manual