![](http://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/avatars/b87/22b/98e/b8722b98eeabd92e72b378cca551c0f1.jpg)
«Все на панель!» или несколько полезных приемов настройки панелей Xwiki
- Tutorial
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/02a/0f9/677/02a0f96779c5ed798229fa58952faae8.png)
В прошлой статье я предложил рассмотреть 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
Не забудьте нажать кнопку "Сохранить".
Выглядеть будет примерно так:
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/5e6/100/6aa/5e61006aa25ad029e17785dcca066938.png)
На странице без заголовков блок не будет видно.
Я специально сделал заголовок "Основы" заголовком второго уровня, чтобы показать уровни вложенности.
Возможно вы захотите немного изменить внешний вид панели, тогда вернемся к её редактированию.
Но прежде убедимся, что у нас включен расширенный режим редактора.
Перейдите на страницу вашего профиля. Нажмите кнопку "Редактировать"
В разделе "Настройки" найдите пункт "Тип пользователя" и выберите значение : "Продвинутый" (Advanced). Теперь нам точно будет доступен редакторов объектов.
Откройте страницу созданной ранее панели, вы можете найти её на странице списка панелей или просто перейдя по адресу {домен}/bin/view/Panels/SideTOC
.
Теперь у кнопки "Редактировать" доступен список с дополнительными вариантами.
Выберите пункт "Объекты".
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/b37/34e/266/b3734e266b718ecc140a898d0de1b479.png)
В поле "Новый объект" выберите StyleSheetExtension и нажмите кнопку "Добавить"
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/1a9/4bf/eaf/1a94bfeaff7233b3322928fcb5091aa4.png)
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;
}
В поле "Использовать это расширение" обязательно выберите "В этой вики" ,
Не забудьте сохранить страницу.
Проверяем нашу главную.
Теперь панель выглядит немного по другому:
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/181/f9d/017/181f9d01730f902998f7735c3a3227a7.png)
Если сходу не нашли 10 отличий, то был добавлен буллет у записей второго уровня и немного изменены отступы.
Миссия выполнена можем переходить к следующему пункту.
Cвоя панель навигации справа / слева
Предположим, что стандартное меню навигации нас не устраивает и мы хотим сделать отдельную панель для очень важного раздела "Моя любимая пицца".
Для начала создадим сам раздел. Пусть он будет в корневом уровне сайта.
Перейдите на главную страницу и нажмите кнопку "Создать".
Введите название и какое-нибудь содержимое в редакторе. Затем аналогичным образом, создайте еще пару дочерних страниц.
Сейчас информация о нашей любимой пицце отображается в разделе "Навигация".
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/c39/08d/71f/c3908d71f015dfbd0113b374b7ae7d6f.png)
Мы хотим убрать эти страницы из раздела "Навигация" и перенести в свою собственную панель.
Для начала уберем ссылки на пиццу из стандартной панели навигации.
В админ-панели откройте раздел "Настройки интерфейса" - > "Панель навигации".
Перетащите раздел "Моя любимая пицца" в раздел "Исключенные страницы".
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/b10/f62/09a/b10f6209a2cc446ab1f504dd07f8b4c1.png)
Теперь перейдите в соседний раздел "Меню" и нажмите кнопку "Добавить новую запись".
Введите название панели, например, PizzaMenu.
Удаляем заглушку. Если у вас WYSIWIG редактор нажмите кнопку "Источник" и вставьте следующий код:
{{documentTree root="document:xwiki:Моя любимая пицца.WebHome" compact="true"/}}
Ну или вы можете просто вставить макрос "Дерево страниц" и добиться также настроек.
В поле "root" первая половина значения - document:xwiki:
- это особенность структуры адресов Xwiki, Вы со временем разберетесь в тонкостях, а вот вторую часть: "Моя любимая пицца.WebHome", можно легко узнать перейдя на страницу "Моя любимая пицца.WebHome" и открыв внизу вкладку "Информация".
В поле "МЕСТО ОТОБРАЖЕНИЯ МЕНЮ" выберите - "Внутри левой панели".
В поле "ОБЛАСТЬ ВИДИМОСТИ МЕНЮ" выберите - "Current Wiki".
Не забудьте сохранить.
Боковые панели к сожалению, не включатся автоматически, их надо добавить вручную.
Перейдите на страницу Админ-панель -> Мастер панелей.
И добавить в левую панель строку: Menu.PizzaMenu.WebHome
Например, вот так:
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/8a5/b99/3f8/8a5b993f881366ffce88f563e7e46131.png)
Сохраняем и наслаждаемся меню (откройте главную страницу чтобы проверить).
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/537/8a2/f5c/5378a2f5ca198a1113ab5f17283c2cdf.png)
Осталось немного навести марафет.
Давайте заменим заголовок панели.
Перейдите на страницу меню. Через админ-панель или просто по адресу:{домен}/bin/view/Menu/PizzaMenu/
Аналогично прошлому разделу откройте редактор объектов.
Разверните "UIExtensionClass" и в тег {{menu}} добавьте: id="PizzaMenu".
Замените значение в "#panelheader("PizzaMenu"), на то что вам больше по душе. Например так:
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/c23/2c5/4a0/c232c54a02bf48735502a5c53456228a.png)
Если хотите можете аналогично примеру с оглавлением подредактировать CSS стиль (именно для этого мы и добавили id="PizzaMenu").
Создайте аналогично прошлому примеру объект для настройки стилей и введите:
#PizzaMenu ul.jstree-children{
padding-left:0px !important;
}
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/e39/d1c/564/e39d1c564cb2fa6459227cb1a20286bc.png)
Сохраняем изменения и видим. что теперь наше меню, практически не отличить от родного меню с навигацией. Если постараетесь можете заменить буллеты и добиться идеального сходства, но я не стал.
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/de2/f06/4f8/de2f064f8be9cae04942cf10d60e5f1d.png)
Добавляем свои советы в панель подсказок
В самом верху справа у нас есть панель случайных подсказок. Допустим мы решим добавить туда несколько своих советов на русском языке.
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/c53/3e1/96e/c533e196e0b2c4d1b884cb1ad2109bb5.png)
Для этого надо в любом месте создать страницу.
Я создам пустую страницу Tips в разделе Xwiki чтобы она не "мозолила" глаза.
Откройте редактор объектов и добавьте объект расширения интерфейса.
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/fb6/3c4/416/fb63c4416de6f58ae8aaa06af28a4498.png)
В поле "Extension Point ID" вставьте: "org.xwiki.platform.help.tipsPanel".
В поле "Extension ID" введите любое название, например, "grammarHelp".
В поле "Extension Scope" выберите "Current Wiki".
В поле "Extension Parameters" введите:
tip = Чтобы воспользоваться исправлением опечатки нажмите Ctrl+ПКМ
Аналогичным образом создайте на странице еще одно расширение. См. скриншот.
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/d63/0a7/4dc/d630a74dc9bb2bc7fdbc96a064e946f2.png)
Остается только сохранить изменения и дождаться появления советов.
![](https://webcf.waybackmachine.org/web/20210411110631im_/https://habrastorage.org/getpro/habr/upload_files/191/7ea/2c5/1917ea2c531725b5858af48c8565d6c9.png)
Если честно я хотел добавить еще примеров, но статья итак получилась объемной.
Впереди у нас интеграция с Figma, GitLab, Swagger и кастомные DocumentThree!
Постараюсь не затягивать со следующим материалом.
Комментарии 0
Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.