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

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

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

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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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