Editor Pro¶

Установка¶

Сначала убедитесь, что у вас установлена последняя версия Grav 1.7 (-f принудительно обновляет индекс GPM).

$ bin/gpm selfupgrade -f

Для полной функциональности Editor Pro требуется Grav 1.7.0 или более поздняя версия.

Через GPM (рекомендуется)¶

$ bin/gpm install editor-pro

Через плагин Admin¶

1. Перейдите в раздел Плагины на боковой панели админки
2. Нажмите кнопку Добавить (значок плюса)
3. Найдите «Editor Pro»
4. Нажмите Установить
5. Нажмите Включить, чтобы активировать

Установка вручную¶

1. Скачайте плагин из своей учётной записи Grav Premium
2. Распакуйте zip-архив в /user/plugins/
3. Переименуйте папку в editor-pro
4. Очистите кэш: bin/grav cache

Конфигурация¶

Перед настройкой плагина скопируйте user/plugins/editor-pro/editor-pro.yaml в user/config/plugins/editor-pro.yaml и редактируйте только эту копию.

Ниже приведена конфигурация по умолчанию и описание доступных параметров:

enabled: true
default_for_all: false
toolbar: 'undo,redo,|,removeformat,|,heading,bold,italic,underline,strikethrough,|,link,image,|,blockquote,bulletList,orderedList,|,codeBlock,table,|,htmlBlock,shortcodeBlock'
extra_typography:
  enabled: true
  custom: []

Параметры конфигурации¶

• enabled — включить или отключить плагин глобально
• default_for_all — назначить Editor Pro редактором по умолчанию для всех пользователей
• toolbar — настроить, какие инструменты отображаются на панели инструментов
• extra_typography.enabled — включить автоматические типографские преобразования
• extra_typography.custom — задать пользовательские замены текста

Настройка редактора по умолчанию¶

Editor Pro можно настроить как редактор по умолчанию на нескольких уровнях:

Глобальное значение по умолчанию (все пользователи)¶

![По умолчанию для всех](global-default.webp?class=image-shadow)

Включите параметр «Default for All Users» в конфигурации плагина, чтобы Editor Pro стал редактором по умолчанию для всех.

Выбор отдельным пользователем¶

![Выбор редактора в профиле](per-user-default.webp?class=image-shadow)

Пользователи могут выбрать предпочитаемый редактор в настройках профиля:

1. Нажмите на свой аватар в админке
2. Выберите «Preferences»
3. Выберите «Editor Pro» в выпадающем списке «Редактор»
4. Сохраните настройки

Настройка для отдельной схемы¶

Укажите Editor Pro для конкретных типов страниц в схемах:

form:
  fields:
    header.content:
      type: editor-pro
      label: Content
      validate:
        required: true

Сочетания клавиш¶

Сочетания клавиш для разных платформ¶

Сочетания клавиш для заголовков¶

Сочетания клавиш для списков и блоков¶

Сочетания клавиш навигации¶

Навигация по таблице¶

Настройка панели инструментов¶

![Настройка панели инструментов](toolbar-config.webp?class=image-shadow)

Панель инструментов можно настроить так, чтобы на ней отображались только нужные инструменты. Доступные элементы панели инструментов:

Форматирование текста¶

• bold — полужирный текст
• italic — курсив
• underline — подчёркнутый текст
• strikethrough — зачёркнутый текст
• code — встроенный код
• subscript — текст нижним индексом
• superscript — текст верхним индексом
• removeformat — очистка форматирования

Структура¶

• heading — выпадающий список заголовков (H1–H6)
• paragraph — формат абзаца
• blockquote — цитата
• horizontalRule — горизонтальная линия

Списки¶

• bulletList — маркированный список
• orderedList — нумерованный список

Контент¶

• link — вставка и изменение ссылки
• image — вставка изображения
• table — вставка таблицы
• codeBlock — блок кода с подсветкой синтаксиса

Специальные блоки¶

• htmlBlock — сохранение блока HTML
• shortcodeBlock — вставка шорткода
• twigBlock — сохранение шаблона Twig
• githubAlert — оповещения в стиле GitHub

История¶

• undo — отменить последнее действие
• redo — повторить последнее действие

Разделители¶

• | — визуальный разделитель на панели инструментов

Пример конфигурации панели инструментов:

toolbar: 'undo,redo,|,heading,bold,italic,|,link,image,|,bulletList,orderedList'

Типы контента¶

Расширенное форматирование текста¶

Editor Pro поддерживает всестороннее форматирование текста:

• Полужирный — сильное выделение (**text** или __text__)
• Курсив — выделение (*text* или _text_)
• Подчёркивание — подчёркнутый текст (<u>text</u>)
• Зачёркивание — зачёркнутый текст (~~text~~)
• Нижний индекс — текст нижним индексом (<sub>text</sub>)
• Верхний индекс — текст верхним индексом (<sup>text</sup>)
• Код — встроенный код (`code`)

Заголовки¶

Поддерживаются шесть уровней заголовков (H1–H6). Используйте выпадающий список на панели инструментов или сочетания клавиш:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Списки¶

Маркированные списки¶

* First item
* Second item
  * Nested item
  * Another nested item
* Third item

Нумерованные списки¶

1. First item
2. Second item
   1. Nested item
   2. Another nested item
3. Third item

Ссылки¶

Ссылки поддерживают заголовки и могут быть внутренними или внешними:

[Link text](https://example.com "Optional title")
[Internal link](/path/to/page)
[Reference link][ref]

[ref]: https://example.com "Reference title"

Изображения¶

Изображения поддерживают alt-текст и заголовки:

![Alt text](image.jpg "Optional title")
![](path/to/image.png)

Перетаскивайте изображения прямо в редактор для автоматической загрузки и вставки.

Таблицы¶

Полноценная поддержка таблиц с визуальным редактированием:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Фичи работы с таблицами: * Добавление и удаление строк и столбцов * Объединение и разделение ячеек * Назначение строк и столбцов заголовками * Изменение ширины столбцов перетаскиванием * Навигация с помощью Tab/Shift+Tab

Блоки кода¶

Блоки кода с подсветкой синтаксиса и выбором языка:

```javascript
function hello() {
    console.log("Hello, World!");
}
```

Поддерживаемые языки включают: * JavaScript/TypeScript * PHP * Python * HTML/CSS * Markdown * YAML/JSON * И многие другие…

Цитаты¶

Вложенные цитаты с корректным форматированием:

> This is a blockquote
> 
> > This is nested
> > 
> > > Even deeper nesting

Оповещения GitHub¶

Встроенная поддержка блоков оповещений в стиле GitHub:

> [!NOTE]
> Useful information that users should know.

> [!TIP]
> Helpful advice for doing things better.

> [!IMPORTANT]
> Key information users need to know.

> [!WARNING]
> Urgent info that needs immediate attention.

> [!CAUTION]
> Advises about risks or negative outcomes.

Визуальные блоки¶

Editor Pro сохраняет специальный контент в виде визуальных блоков, чтобы предотвратить его повреждение:

Блоки необработанного кода (тёмно-серые)¶

![Блоки необработанного кода](raw-code.webp?class=image-shadow)

Необработанный код — это контент HTML или Twig; он сохраняется в виде синих блоков:

• Предотвращает случайное изменение
• Сохраняет исходное форматирование
• Редактирование на месте с подсветкой синтаксиса
• Поддерживает любой допустимый HTML или Twig, начинающийся с новой строки

Пример:

{% for item in page.collection %}
  <h2>{{ item.title }}</h2>
  {{ item.content|raw }}
{% endfor %}

Пример:

<div class="custom-widget">
  <h3>Custom HTML</h3>
  <p>This HTML is preserved exactly as written.</p>
</div>

Блоки шорткодов (зелёные)¶

![Блоки шорткодов](shortcode.webp?class=image-shadow)

Шорткоды отображаются в виде зелёных блоков с визуальными индикаторами:

• Показывает имя шорткода и параметры
• Нажмите, чтобы изменить через модальное окно
• Поддерживает вложенные шорткоды
• Предпросмотр в реальном времени, когда доступен

Пример:

[columns count="2"]  
[column]First column[/column]  
[column]Second column[/column]  
[/columns]  

Типографские преобразования¶

![Настройки типографики](transforms.webp?class=image-shadow)

Editor Pro может автоматически преобразовывать текстовые шаблоны по мере ввода.

Встроенные преобразования¶

Типографика¶

• -- → — (длинное тире)
• ... → … (многоточие)
• (c) → © (знак копирайта)
• (r) → ® (зарегистрированный знак)
• (tm) → ™ (торговая марка)

Кавычки¶

• "text" → "text" (умные кавычки)
• 'text' → 'text' (умные одинарные кавычки)

Стрелки¶

• -> → →
• <- → ←
• <-> → ↔
• => → ⇒

Дроби¶

• 1/2 → ½
• 1/3 → ⅓
• 1/4 → ¼
• 3/4 → ¾

Математические символы¶

• +- → ±
• != → ≠
• <= → ≤
• >= → ≥

Пользовательские преобразования¶

Добавьте собственные преобразования в конфигурации:

extra_typography:
  enabled: true
  custom:
    ':)': '😊'
    ':(': '😢'
    ':D': '😃'
    '->': '→'
    '<3': '❤️'

Преобразования для отдельных языков¶

Настройте преобразования для каждого языка:

extra_typography:
  languages:
    fr:
      quotes: ['« ', ' »']
      custom:
        'oe': 'œ'
    de:
      quotes: ['„', '"']

Интеграция шорткодов¶

При использовании с плагином shortcode-core Editor Pro предоставляет расширенную поддержку шорткодов.

Модальное окно шорткодов¶

![Модальное окно шорткодов](shortcode-modal.webp?class=image-shadow&width=600px)

Нажмите Ctrl/⌘ + Shift + S, чтобы открыть модальное окно шорткодов:

1. Поиск шорткодов по имени или описанию
2. Настройка параметров через поля формы
3. Предпросмотр результата (если предпросмотр доступен)
4. Вставка шорткода в ваш контент

Поддерживаемые типы полей¶

• Текст — однострочное поле ввода
• Многострочный текст — многострочное поле ввода
• Выбор — выбор из выпадающего списка
• Флажок — логический переключатель
• Число — числовой ввод
• Цвет — выбор цвета
• Дата — выбор даты
• Файл — выбор файла или медиафайла
• Страница — выбор страницы

Вложенные шорткоды¶

Сложные шорткоды с иерархией «родитель — потомок»:

[tabs]
  [tab title="First"]
    First tab content
  [/tab]
  [tab title="Second"]
    Second tab content
  [/tab]
[/tabs]

Предпросмотр в реальном времени¶

Если включено, шорткоды отображают предпросмотр в реальном времени в редакторе:

plugins:
  shortcode-core:
    live_preview: true
    preview_delay: 500  # миллисекунды

Расширение Editor Pro¶

Интеграция плагинов¶

Зарегистрируйте свой плагин в Editor Pro:

<?php
namespace Grav\Plugin;

use Grav\Common\Plugin;

class YourPlugin extends Plugin
{
    public static function getSubscribedEvents()
    {
        return [
            'registerEditorProPlugin' => ['registerEditorProPlugin', 0]
        ];
    }

    public function registerEditorProPlugin($event)
    {
        $plugins = $event['plugins'];

        // Добавить CSS
        $plugins['css'][] = 'plugin://your-plugin/assets/editor-pro.css';

        // Добавить JavaScript
        $plugins['js'][] = 'plugin://your-plugin/assets/editor-pro.js';

        $event['plugins'] = $plugins;
        return $event;
    }
}

JavaScript API¶

Обращайтесь к API Editor Pro в своём JavaScript:

window.EditorPro.registerPlugin({
    name: 'your-plugin',

    init(editorPro) {
        const { editor, toolbar, schema } = editorPro;

        // Добавить пользовательскую кнопку
        toolbar.addButton({
            name: 'customButton',
            icon: '🎨',
            title: 'Custom Action',
            action: () => {
                // Ваше пользовательское действие
                editor.chain()
                    .focus()
                    .insertContent('Custom content')
                    .run();
            }
        });

        // Слушать события редактора
        editor.on('update', ({ editor }) => {
            console.log('Content updated');
        });

        // Доступ к состоянию редактора
        editor.on('selectionUpdate', ({ editor }) => {
            const { from, to } = editor.state.selection;
            console.log(`Selection: ${from} to ${to}`);
        });
    }
});

Пользовательские узлы¶

Создавайте пользовательские узлы TipTap:

import { Node } from '@tiptap/core';

export const CustomWidget = Node.create({
    name: 'customWidget',

    group: 'block',

    content: 'inline*',

    addAttributes() {
        return {
            type: {
                default: 'default',
            },
        };
    },

    parseHTML() {
        return [
            {
                tag: 'div[data-widget]',
            },
        ];
    },

    renderHTML({ HTMLAttributes }) {
        return ['div', { 'data-widget': '', ...HTMLAttributes }, 0];
    },

    addCommands() {
        return {
            setWidget: (attributes) => ({ commands }) => {
                return commands.setNode(this.name, attributes);
            },
        };
    },
});

Пользовательские марки¶

Создавайте пользовательские текстовые марки:

import { Mark } from '@tiptap/core';

export const Highlight = Mark.create({
    name: 'highlight',

    addAttributes() {
        return {
            color: {
                default: 'yellow',
            },
        };
    },

    parseHTML() {
        return [
            {
                tag: 'mark',
            },
        ];
    },

    renderHTML({ HTMLAttributes }) {
        return ['mark', HTMLAttributes, 0];
    },

    addCommands() {
        return {
            toggleHighlight: (attributes) => ({ commands }) => {
                return commands.toggleMark(this.name, attributes);
            },
        };
    },
});

Расширенная конфигурация¶

Конфигурация для отдельной страницы¶

Управляйте поведением Editor Pro для каждой страницы:

---
title: My Page
editor_pro:
  enabled: true
  toolbar: 'bold,italic,link'
  preserve_html: false
  preserve_twig: true
  typography:
    enabled: false
---

Параметры поля схемы¶

Расширенная конфигурация поля в схемах:

form:
  fields:
    content:
      type: editor-pro
      label: Content
      toolbar: 'heading,bold,italic,link,image'
      height: 500
      autofocus: true
      placeholder: 'Start writing...'
      typography:
        enabled: true
        arrows: true
        quotes: true
      preserve:
        html: true
        shortcodes: true
        twig: false

Правила сохранения контента¶

Настройте, какие типы контента сохранять:

plugins:
  editor-pro:
    preserve:
      html:
        enabled: true
        tags: ['script', 'style', 'iframe']
      shortcodes:
        enabled: true
        list: ['notice', 'columns', 'tabs']
      twig:
        enabled: true
        patterns: ['{{', '{%', '{#']

Оптимизация производительности¶

Большие документы¶

Для документов объёмом более 50 000 слов:

plugins:
  editor-pro:
    performance:
      lazy_blocks: true
      debounce_save: 1000
      max_history: 50

Управление памятью¶

Оптимизируйте использование памяти:

plugins:
  editor-pro:
    performance:
      clear_history_on_save: true
      compress_history: true
      max_document_size: 5000000  # 5MB

Решение проблем¶

Редактор не появляется¶

1. Проверьте, что плагин включён

   bin/gpm status editor-pro
   

2. Очистите кэш

   bin/grav cache
   

3. Проверьте настройку пользователя

4. Проверьте выбор редактора в профиле пользователя

5. Убедитесь, что выбран «Editor Pro»

6. Проверьте консоль браузера

7. Откройте инструменты разработчика (F12)
8. Найдите ошибки JavaScript
9. Сообщите об обнаруженных ошибках

Контент не сохраняется¶

1. Проверьте права доступа

   ls -la user/pages/
   

2. Проверьте обработку формы

3. Проверьте наличие ошибок валидации формы

4. Убедитесь, что обязательные поля заполнены

5. Протестируйте с простым контентом

6. Попробуйте сохранить только простой текст
7. Постепенно добавляйте сложный контент

Шорткоды не работают¶

1. Проверьте, что shortcode-core установлен

   bin/gpm status shortcode-core
   

2. Проверьте регистрацию шорткодов

3. Убедитесь, что шорткоды зарегистрированы правильно

4. Проверьте, что слушатели событий настроены

5. Включите режим отладки

   plugins:
     editor-pro:
       debug: true
   

Проблемы с производительностью¶

1. Проверьте размер документа
2. Большим документам могут потребоваться настройки оптимизации

3. Подумайте о разделении очень длинного контента

4. Отключите предпросмотр в реальном времени

   plugins:
     shortcode-core:
       live_preview: false
   

5. Сократите число элементов панели инструментов

6. Включайте только необходимые инструменты
7. Сведите к минимуму пользовательские расширения

Совместимость с браузерами¶

1. Проверьте версию браузера
2. Убедитесь, что браузер соответствует минимальным требованиям

3. При необходимости обновите до последней версии

4. Отключите расширения браузера

5. Блокировщики рекламы могут мешать

6. Попробуйте режим инкогнито или приватный режим

7. Проверьте в другом браузере

8. Попробуйте Chrome, если используете Firefox
9. Убедитесь, что проблема связана с конкретным браузером

Руководство по миграции¶

С NextGen Editor¶

1. Установите Editor Pro

   bin/gpm install editor-pro
   

2. Обновите настройки пользователей

3. Измените выбор редактора на «Editor Pro»

4. Миграция контента не требуется

5. Обновите пользовательские интеграции

6. Измените имена событий с registerNextGenEditorPlugin на registerEditorProPlugin

7. Обновите вызовы JavaScript API

8. Тщательно протестируйте

9. Проверьте все типы страниц
10. Убедитесь в работоспособности шорткодов
11. Проверьте пользовательские расширения

С редактора Markdown¶

1. Контент полностью совместим
2. Преобразование не требуется

3. Структура Markdown сохраняется

4. Включайте постепенно

5. Начните с отдельных типов страниц

6. Постепенно внедряйте у пользователей

7. Обучите пользователей

8. Предоставьте справочник по сочетаниям клавиш
9. Объясните концепцию визуальных блоков

Справочник API¶

События PHP¶

registerEditorProPlugin¶

Регистрация ресурсов и конфигурации:

public function registerEditorProPlugin($event)
{
    $plugins = $event['plugins'];
    $config = $event['config'];

    // Добавить ресурсы
    $plugins['js'][] = 'plugin://your-plugin/editor.js';
    $plugins['css'][] = 'plugin://your-plugin/editor.css';

    // Добавить конфигурацию
    $config['custom_setting'] = true;

    $event['plugins'] = $plugins;
    $event['config'] = $config;
    return $event;
}

onEditorProSave¶

Обработка контента перед сохранением:

public function onEditorProSave($event)
{
    $content = $event['content'];
    $page = $event['page'];

    // Обработать контент
    $content = $this->processContent($content);

    $event['content'] = $content;
    return $event;
}

JavaScript API¶

Экземпляр редактора¶

Доступ к редактору TipTap:

const editor = window.EditorPro.getEditor(fieldId);

// Получить/установить контент
editor.getHTML();
editor.getJSON();
editor.getText();
editor.setContent(content);

// Команды
editor.chain().focus().bold().run();
editor.chain().focus().insertContent('text').run();

// Состояние
editor.isActive('bold');
editor.can().bold();

API панели инструментов¶

Управление элементами панели инструментов:

const toolbar = window.EditorPro.getToolbar(fieldId);

// Добавить кнопку
toolbar.addButton({
    name: 'custom',
    icon: '🎨',
    title: 'Custom',
    action: callback
});

// Удалить кнопку
toolbar.removeButton('custom');

// Обновить кнопку
toolbar.updateButton('custom', {
    disabled: true
});

API схемы¶

Доступ к схеме документа и её изменение:

const schema = window.EditorPro.getSchema(fieldId);

// Зарегистрировать узел
schema.registerNode('customNode', nodeSpec);

// Зарегистрировать марку
schema.registerMark('customMark', markSpec);

// Получить узел/марку
schema.getNode('paragraph');
schema.getMark('bold');

Поддержка¶

Как получить помощь¶

1. Документация — это подробное руководство
2. Задачи GitHub — сообщить об ошибках
3. Discord — присоединиться к Grav Discord
4. Форум — форум Grav

Сообщение о проблемах¶

При сообщении о проблемах указывайте:

1. Версия Grav (bin/grav version)
2. Версия Editor Pro
3. Браузер и его версия
4. Шаги для воспроизведения
5. Сообщения об ошибках из консоли
6. Соответствующая конфигурация

Запросы фич¶

Отправляйте запросы на новые фичи на GitHub с указанием:

1. Описание сценария использования
2. Ожидаемое поведение
3. Макеты или примеры, если применимо
4. Приоритет и срочность

Благодарности¶

• TipTap — современный фреймворк редактора
• ProseMirror — базовый движок редактора
• Grav Team — платформа CMS
• Trilby Media — разработка плагина