Документерра: руководство пользователя

Экспресс-блоки

Экспресс-блоки —это небольшие фрагменты, которые можно вставлять в контент. Они помогают ускорить выполнение рутинных задач, таких как вставка определенных повторяющихся фрагментов контента в документацию. Вы можете создать экспресс-блок из любого фрагмента вашего контента, включая переменные, сниппеты, условные блоки и др.

Для быстрого перехода к определенному разделу данной страницы используйте следующие ссылки:

По умолчанию в системе Документерра доступно более десяти экспресс-блоков, включая информационное окно, окно предупреждения, элемент «Меню действий» и экспресс-блоки API.

В отличие от сниппетов, экспресс-блоки —это фрагменты контента, которые вставляются непосредственно на страницу. После вставки экспресс-блока он становится частью контента страницы, что позволяет изменять его на месте. Это похоже на вставку контента из буфера обмена.

Важно

Совместное использование экспресс-блоков осуществляется в масштабах портала, что означает, что каждый пользователь имеет один и тот же список экспресс-блоков. Не существует специфических для конкретного проекта или пользователя экспресс-блоков.

Создание экспресс-блока

Чтобы создать новый экспресс-блок, выполните несколько простых действий:

Выберите контент страницы, на основе которого необходимо создать экспресс-блок.

	Совет
Если вы хотите создать экспресс-блок из пользовательского HTML, прочитайте инструкцию , приведенную ниже.

Выберите в верхней панели вкладку Вставка и нажмите кнопку Создать из выбранного в группе Экспресс-блоки. В качестве альтернативы нажмите Ctrl+Q (Command-Q в MacOS)
Появится диалоговое окно Создание экспресс-блока.
- Необходимо указать имя экспресс-блока. Если указать (или выбрать из списка) имя уже существующего экспресс-блока, то существующий экспресс-блок будет перезаписан новым.
- Щелкните на ссылке Показать исходный код экспресс-блока, чтобы увидеть HTML-файл экспресс-блока. Вы также можете отредактировать его, если необходимо изменить что-то в процессе работы или очистить разметку.

Вставка экспресс-блока

Процесс вставки экспресс-блока довольно прост:

Переключитесь на вкладку Вставка в верхней панели и нажмите кнопку Вставка группы Экспресс-блоки.
Щелкните на нужном экспресс-блоке из списка.

Экспресс-блок будет вставлен в место расположения текстового курсора.

Редактирование экспресс-блока

Редактировать уже существующий экспресс-блок нельзя, но можно заменить его на новый:

Создайте новую страницу. Удалите из нее весь контент.
Этот шаг необходим для того, чтобы лишний HTML-код случайно не попал в код экспресс-блока.
Вставьте экспресс-блок на страницу.
Отредактируйте его по своему усмотрению.
Переключитесь в режим исходного кода и скопируйте отредактированный исходный HTML-код экспресс-блока.
Переключитесь обратно в режим «Дизайн» и выделите всё (Ctrl+A).
На вкладке «Вставка» в верхней панели нажмите кнопку Создать из выделенного.
Во всплывающем окне нажмите Показать исходный код экспресс-блока.
Замените исходный код, который в данный момент находится в области ввода, на тот, который был скопирован на шаге 4.
Введите имя редактируемого экспресс-блока. Появится сообщение о том, что существующий экспресс-блок с таким именем будет перезаписан.
Нажмите OK.

Переименование экспресс-блока

Как и в случае с редактированием, переименовать существующий экспресс-блок в настоящее время невозможно. Вот что можно сделать для этой цели:

Вставка экспресс-блока на страницу
Выберите его на странице
Щелкните Создать из выделенного на вкладке «Вставка» в верхней панели.
Введите новое имя для экспресс-блока
Удаление старого экспресс-блока

Удаление экспресс-блока

Любой пользователь с правами доступа автора, кроме рецензентов, может удалить экспресс-блок.

	Внимание
Если вы удалите экспресс-блок, он будет удален для всех пользователей портала.

Наведите указатель мыши на конкретный экспресс-блок во всплывающем окне «Вставка экспресс-блока»
Нажмите кнопку Удалить (иконка с изображением ведра).

Экспресс-блоки для API-документации

Документерра предоставляет несколько стандартных элементов, популярных в документах API, уже в готовом виде. Помимо того, что они доступны в меню вставки экспресс-блоков, связанные с API экспресс-блоки также доступны на отдельной вкладке в верхней панели:

Вкладка «Экспресс-блоки для API-документации» в верхней панели

Это отличная отправная точка, которую можно использовать, чтобы ускорить процесс написания документации по API. С помощью этих «строительных кирпичей» можно быстро собрать типовые страницы документации по API. Например, таблица элементов может использоваться для описания как параметров запроса, так и полей ответа.

Внимание

Если вы удалите экспресс-блок для API-документации из меню вставки экспресс-блоков, то не сможете вставить его, нажав соответствующую кнопку на вкладке API-документации в верхней панели. Для восстановления работоспособности кнопок в верхней панели необходимо создать экспресс-блок с соответствующим именем.

Часто задаваемые вопросы

Можно ли настроить экспресс-блоки для API-документации?

Да. Поскольку эти элементы являются экспресс-блоками, их можно настраивать как по разметке, так и по стилю. Чтобы узнать, как модифицировать экспресс-блоки, обратитесь к соответствующему разделу выше.

Совет

Чтобы изменить внешний вид и функциональность экспресс-блоков для API-документации, найдите в CSS-файлах проектов соответствующие правила CSS, добавленные автоматически при обновлении портала в разделе с заголовком /* Элементы API-документации —начало */.

Можно ли создавать новые экспресс-блоки для API-документации?

Да. Как и в случае с любыми другими экспресс-блоками, вы можете таким же образом добавлять экспресс-блоки для API-документов. Чтобы узнать, как это сделать, смотри соответствующий раздел выше.

	Примечание
При создании пользовательских экспресс-блоков для API-документации, которые не предоставляются в готовом виде, они не будут отображаться в виде кнопок на верхней панели на вкладке API-документации.

Чем экспресс-блоки отличаются от сниппетов?

Хотя на первый взгляд разница между экспресс-блоками и сниппетами контента может быть неочевидна и они могут показаться похожими, по своей сути они сильно отличаются.

Экспресс-блоки	Сниппеты
Разметка экспресс-блока становится частью разметки страницы при вставке	Разметка сниппета становится частью разметки страницы при публикации
Хранятся в данных портала, вне страниц	Должны существовать как отдельные страницы
Возможность редактирования при вставке	Не могут быть отредактированы на странице, в которую они вставлены
Если на странице редактируется один из вставленных экспресс-блоков, то изменения вносятся только в редактируемый объект	При редактировании исходного сниппета изменения отражаются в каждом вставленном экземпляре этого сниппета во всех проектах

Я случайно удалил экспресс-блок, что мне делать?

Вы всегда можете создать новый, следуя инструкциям, приведенным выше. Некоторые из стандартных HTML-кодов экспресс-блоков можно найти в нашей базе знаний.

Как создать экспресс-блок из пользовательского HTML-кода?

Выберите что-либо на странице, чтобы активировать кнопку Создать из выбранного.
Нажмите кнопку Создать из выбранного.
Во всплывающем окне нажмите кнопку Показать исходный код экспресс-блока.
Замените исходный код на свой собственный пользовательский HTML-код.
Не забудьте указать имя экспресс-блока и нажмите кнопку OK.

Добавление готовых элементов Раскрываемое поле