В прошлой статье я
предложил рассмотреть Xwiki, как бесплатную замену Confluence и
заодно пообещал поделиться несколькими советами по настройке.
Вот уже больше полугода я использую Xwiki в качестве базы знаний
для небольшой команды разработчиков.
В процессе работы у меня возникали определенные трудности,
документация не помогала, а ответов на англоязычном форуме
приходилось ждать с большим вожделением, чем первого глотка пива в
выходной.
Мне бы хотелось облегчить жизнь энтузиастам из волшебного мира
документирования, поэтому я решил поделится своими наработками.
На текущий момент я планирую подготовить мини цикл из четырех -
пяти статей про Xwiki.
В первой статье мы погорим о простых вещах, которые не отнимут у
нас много времени, а именно:
-
как сделать оглавление страницы в боковой панели;
-
как сделать свою панель навигации;
-
как добавить свои советы в панель подсказок;
-
за одно узнаем, как сделать аннотацию на странице;
-
также узнаем, как использовать проверку орфографии в WYSIWIG редакторе;
-
Прежде чем мы начнем, хочу признаться, что я далеко не "гуру" в
программировании и настройке Xwiki, так, что это просто "не очень
элегантные" советы, которые тем не менее работают.
Весь материал статьи я проверял в версиях Xwiki 12.10.5 и 13.2 с
установленной Demo Flavor. Также в статье подразумевается, что вы
обладаете правами администратора.
Оглавление страницы в боковой панели
В админ-панели переходим в раздел Настройки интерфейса ->
Мастер панелей и внизу страницы находим ссылку "Перейти к панелям".
Ну или просто введите в адресную строку
{ваш домен с Xwiki}/bin/view/Panels/
Введите название панели (например, SideTOC}
Тип панели оставьте - "View"
Описание - на ваше усмотрение.
В поле Содержимое введите код:
{{velocity}}{{context document="$services.model.serialize($doc.documentReference)" transformationContext="document"}}#set ($hasHeaders = [])#set ($mydoc = $doc.getDocument())#foreach ($block in $mydoc.getXDOM().getBlocks('class:HeaderBlock', 'DESCENDANT')) #set ($discard = $hasHeaders.add($block))#end#if($hasHeaders.size()>0) #panelheader('Table of Contents') {{box cssClass="sidetoc"}}{{toc/}}{{/box}}#end{{/context}}{{/velocity}}
Поясню для тех, кто только начал знакомство с данной Вики.
В Xwiki для автоматизации используется различные средства
автоматизации и одно из них Appache Velocity. В данном
случае весь код между тегами {{velocity}} {{/velocity}} будет
обрабатываться как код на данном языке шаблонов.
В макросе {{context}} мы указываем контекст для которого будет
выполнятся наш код.
В нашем случае это контекст основного содержимого страницы. Таким
образом, наш скрипт будет думать, что он не внутри сквозной боковой
панели, а внутри блока с текстом статьи. Это необходимо для того,
чтобы получить заголовки из которых формируется оглавление.
блок
#if($hasHeaders.size()>0) #panelheader('Table of
Contents') {{box cssClass="sidetoc"}}{{toc/}}{{/box}}
#panelheader('Table of Contents')
#end
Выводит нам заголовок для панели и сами ссылки на разделы статьи,
только в том случае если на странице есть заголовки из которых
можно собрать оглавление.
Макрос {{toc/}} - непосредственно создает оглавление. Мы обрамим
его в макрос
{{box cssClass="sidetoc"}}, чтобы иметь возможность
удобной стилизации блока. Но об этом немного позже.
Теперь необходимо вставить нашу панель в верстку страницы.
Я решил разместить блок слева.
Чтобы сделать также в админ-панели перейдите на страницу Мастер
панелей -> вкладка "Список панелей" и просто перетащите панель с
названием SideTOC на панель слева (справа).
Если перетаскивание не сработает, вы можете добавить панель в
ручную
На вкладке "Макет страницы" в поле "ПАНЕЛИ СЛЕВА" (или справа)
добавив "Panels.SideTOC".
например,
Panels.Applications,Panels.Navigation,Panels.SideTOC
Не забудьте нажать кнопку "Сохранить".
Выглядеть будет примерно так:
На странице без заголовков блок не будет видно.
Я специально сделал заголовок "Основы" заголовком второго уровня,
чтобы показать уровни вложенности.
Возможно вы захотите немного изменить внешний вид панели, тогда
вернемся к её редактированию.
Но прежде убедимся, что у нас включен расширенный режим
редактора.
Перейдите на страницу вашего профиля. Нажмите кнопку
"Редактировать"
В разделе "Настройки" найдите пункт "Тип пользователя" и выберите
значение : "Продвинутый" (Advanced). Теперь нам точно
будет доступен редакторов объектов.
Откройте страницу созданной ранее панели, вы можете найти её на
странице списка панелей или просто перейдя по адресу
{домен}/bin/view/Panels/SideTOC.
Теперь у кнопки "Редактировать" доступен список с
дополнительными вариантами.
Выберите пункт "Объекты".
В поле "Новый объект" выберите StyleSheetExtension и нажмите кнопку "Добавить"
Xwiki очень функциональна и позволяет поменять css стили
практически для любого элемента. В данном случае мы поменяем стиль
класса siidetoc, который был указан в макросе {box}.
Введите любое название например sidetoc, а затем CSS код:
.sidetoc { border:0px; margin:0px; padding:0px; width:100%;}.sidetoc ul { padding-left:2px; list-style-type:disc; font-size:1em; padding:0px; margin-left:0px;}.sidetoc li { padding-left: 0px; margin-left:5px; list-style-type:disc;}
В поле "Использовать это расширение" обязательно выберите "В этой вики" ,
Не забудьте сохранить страницу.
Проверяем нашу главную.
Теперь панель выглядит немного по другому:
Если сходу не нашли 10 отличий, то был добавлен буллет у записей
второго уровня и немного изменены отступы.
Миссия выполнена можем переходить к следующему пункту.
Cвоя панель навигации справа / слева
Предположим, что стандартное меню навигации нас не устраивает и
мы хотим сделать отдельную панель для очень важного раздела "Моя
любимая пицца".
Для начала создадим сам раздел. Пусть он будет в корневом уровне
сайта.
Перейдите на главную страницу и нажмите кнопку
"Создать".
Введите название и какое-нибудь содержимое в редакторе. Затем
аналогичным образом, создайте еще пару дочерних страниц.
Сейчас информация о нашей любимой пицце отображается в разделе "Навигация".
Мы хотим убрать эти страницы из раздела "Навигация" и перенести
в свою собственную панель.
Для начала уберем ссылки на пиццу из стандартной панели
навигации.
В админ-панели откройте раздел "Настройки интерфейса" - >
"Панель навигации".
Перетащите раздел "Моя любимая пицца" в раздел "Исключенные
страницы".
Теперь перейдите в соседний раздел "Меню" и нажмите кнопку
"Добавить новую запись".
Введите название панели, например, PizzaMenu.
Удаляем заглушку. Если у вас WYSIWIG редактор нажмите кнопку
"Источник" и вставьте следующий код:
{{documentTree root="document:xwiki:Моя любимая пицца.WebHome" compact="true"/}}
Ну или вы можете просто вставить макрос "Дерево страниц" и
добиться также настроек.
В поле "root" первая половина значения -
document:xwiki: - это особенность структуры адресов
Xwiki, Вы со временем разберетесь в тонкостях, а вот вторую часть:
"Моя любимая пицца.WebHome", можно легко узнать перейдя на страницу
"Моя любимая пицца.WebHome" и открыв внизу вкладку
"Информация".
В поле "МЕСТО ОТОБРАЖЕНИЯ МЕНЮ" выберите - "Внутри левой
панели".
В поле "ОБЛАСТЬ ВИДИМОСТИ МЕНЮ" выберите - "Current
Wiki".
Не забудьте сохранить.
Боковые панели к сожалению, не включатся автоматически, их надо
добавить вручную.
Перейдите на страницу Админ-панель -> Мастер панелей.
И добавить в левую панель строку:
Menu.PizzaMenu.WebHome
Например, вот так:
Сохраняем и наслаждаемся меню (откройте главную страницу чтобы проверить).
Осталось немного навести марафет.
Давайте заменим заголовок панели.
Перейдите на страницу меню. Через админ-панель или просто по
адресу:{домен}/bin/view/Menu/PizzaMenu/
Аналогично прошлому разделу откройте
редактор объектов.
Разверните "UIExtensionClass" и в тег {{menu}} добавьте:
id="PizzaMenu".
Замените значение в "#panelheader("PizzaMenu"), на то что вам
больше по душе. Например так:
Если хотите можете аналогично примеру с оглавлением
подредактировать CSS стиль блока (именно для этого мы и добавили
id="PizzaMenu").
Создайте объект для настройки стилей и введите:
#PizzaMenu ul.jstree-children{ padding-left:0px !important;}
Сохраняем изменения и видим. что теперь наше меню, практически не отличить от родного меню с навигацией. Если постараетесь можете заменить буллеты и добиться идеального сходства, но я не стал.
Добавляем свои советы в панель подсказок
В самом верху справа у нас есть панель случайных подсказок. Допустим мы решим добавить туда несколько своих советов на русском языке.
Для этого надо в любом месте создать страницу.
Я создам пустую страницу Tips в разделе Xwiki чтобы она не
"мозолила" глаза.
Откройте редактор объектов и добавьте объект расширения интерфейса.
В поле "Extension Point ID" вставьте:
"org.xwiki.platform.help.tipsPanel".
В поле
"Extension ID" введите любое название, например, "grammarHelp".
В поле "Extension Scope" выберите "Current Wiki".
В поле "Extension Parameters" введите:
tip = Чтобы воспользоваться исправлением опечатки нажмите
Ctrl+ПКМ
Аналогичным образом создайте на странице еще одно расширение. См. скриншот.
Остается только сохранить изменения и дождаться появления советов.
Если честно я хотел добавить еще примеров, но статья итак
получилась объемной.
Впереди у нас интеграция с Figma, GitLab, Swagger и кастомные
DocumentThree!
Постараюсь не затягивать со следующим материалом.
