Разработка Grav⚓︎

Если вы хотите разрабатывать с помощью Grav, вы получите более сложную настройку, чем та, которая требуется для обычного пользователя Grav. Это включает практически любой тип разработки, например: Grav Core, Grav Plugins, Grav Skeletons или даже Grav Themes.

Во-первых, давайте разберем различные типы развития:

Grav Core⚓︎

Когда мы говорим о Grav Core, мы фактически говорим о вещах в папке system. Эта папка контролирует все, что касается Grav, и на самом деле является самой сутью рабочего процесса и жизненного цикла Grav.

Grav намеренно сосредоточен на эффективной работе со страницами. Для управления страницами и расширенной функциональности часто лучше всего создать плагин. Мы настоятельно рекомендуем нашему сообществу вносить исправления и даже предлагать разработку соответствующих функций в ядре Grav.

Запуск тестов⚓︎

Сначала установите зависимости для разработки, запустив composer install из корня Grav.

composer install

Затем вы можете запустить тесты:

composer test

Это запустит полный набор существующих тестов, которые всегда должны успешно выполняться на любом сайте.

Вы также можете запустить один файл модульного теста, например

composer test tests/unit/Grav/Common/Markdown/ParsedownTest::testAttributeLinks

Альтернативный метод вызова этих тестов:

./vendor/bin/codecept run
./vendor/bin/codecept run tests/unit/Grav/Common/Markdown/ParsedownTest::testAttributeLinks

Плагины Grav⚓︎

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

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

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

Требования плагинов⚓︎

Хороший плагин Grav требует определённых файлов для правильной работы, чтобы попасть в репозиторий Grav и отображаться в плагине админки. Убедитесь, что ваш плагин содержит все эти файлы:

• yourplugin.php - PHP файл плагина, который должен называться так же, как и папка
• yourplugin.yaml - файл конфигурации плагина, который содержит любые параметры и информацию о наследовании потоков
• blueprints.yaml - файл определения плагина и файл определения формы
• CHANGELOG.md - файл журнала изменений, который должен быть в правильном формате Grav для согласованного рендеринга
• README.md - необходимый файл для объяснения и предварительного просмотра плагина
• LICENSE - файл лицензии, возможно, MIT, если он соответствует ядру Grav
• languages.yaml (необязательно) - файл определения языка

Каркасы Grav⚓︎

Grav Skeleton — это универсальный образец сайта. Они включают Grav Core, необходимые плагины, а также соответствующие страницы для контента и тему для объединения всего этого.

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

Эти каркасы являются основой, на которой вы можете быстро и эффективно развивать свой сайт. Вы не привязаны к определенному набору функций. Он так же гибок, как и любая другая установка Grav.

Требования каркасов⚓︎

Хороший каркас Grav требует определённых файлов для правильной работы, чтобы попасть в репозиторий Grav и отображаться в плагине админки. Убедитесь, что ваш каркас содержит все эти файлы:

• .dependencies - файл для определения зависимостей темы и плагина для этого скелета.
• blueprints.yaml - файл определения скелета и файл определения формы
• CHANGELOG.md - файл журнала изменений, который должен быть в правильном формате Grav для согласованного рендеринга
• README.md - required file to explain and preview the plugin
• LICENSE - файл лицензии, возможно, MIT, если он соответствует ядру Grav
• screenshot.jpg - предварительный просмотр темы с соотношением сторон 1:1. Должно быть не менее 800x800 пикселей.

Темы Grav⚓︎

Из-за тесной связи со страницами и темами Grav тема Grav является неотъемлемой и очень важной частью сайта Grav. Под этим мы подразумеваем, что каждая страница Grav ссылается на шаблон в теме, поэтому ваша тема должна предоставлять соответствующие шаблоны Twig, которые используют ваши страницы.

Движок шаблонов Twig - очень мощная система, и поскольку Grav действительно не накладывает никаких ограничений, вы можете создавать любой дизайн, какой захотите. Это одна из замечательных особенностей Grav, которая отличает Grav от традиционной CMS, имеющей слабую связь между контентом и дизайном.

Требования тем⚓︎

Хорошая тема Grav требует определённых файлов для правильной работы, чтобы попасть в репозиторий Grav и отображаться в плагине админки. Убедитесь, что ваша тема содержит все эти файлы:

• yourtheme.php - PHP файл темы, который должен называться так же, как папка
• yourtheme.yaml - файл конфигурации темы, который содержит любые параметры и информацию о наследовании потока
• blueprints.yaml - файл определения темы и файл определения формы
• CHANGELOG.md - файл журнала изменений, который должен быть в правильном формате Grav для согласованного рендеринга
• README.md - требуемый файл для объяснения и предварительного просмотра темы
• LICENSE - файл лицензии, возможно, MIT, если он соответствует ядру Grav
• screenshot.jpg - предварительный просмотр темы с соотношением сторон 1:1. Должно быть не менее 800x800 пикселей.
• thumbnail.jpg - уменьшенное изображение эскиза, используемое плагином админки. Соотношение сторон 1:1 и должно быть 300x300 пикселей.
• languages.yaml (необязательно) - файл определения языка

Демо-контент⚓︎

С выпуском Grav 0.9.18 вы теперь можете предоставлять демонстрационный контент как часть плагина или пакета темы. Это означает, что всё, что находится в папке с именем _demo/, будет скопировано в папку user/ как часть процедуры установки. Это означает, что вы можете предоставить страницы, конфигурацию или что-нибудь ещё, что находится в папке user/. Пользователю предлагается сделать это, и это совершенно необязательно.

Обратите внимание, что демонстрационный контент не копируется, если ваш плагин или тема установлены через плагин Admin.

Процесс выпуска темы/плагина⚓︎

Когда вы создали новую тему или плагин и хотели бы, чтобы они были добавлены в репозиторий Grav, вам необходимо выполнить несколько стандартных действий:

1. Добавить файл LICENSE, содержащий MIT-совместимую лицензию. Пример здесь
2. Добавить файл README.md с описанием функций и инструкциями по его установке и настройке. Пример здесь
3. Добавить файл blueprints.yaml со всеми обязательными полями. Пример здесь
4. Предоставить CHANGELOG.md в правильном формате. Пример здесь
5. Перечислить используемые библиотеки, скрипты, код.
6. Создать релиз для плагина/темы. Система репозитория Grav требует наличия релиза и не найдет ваш плагин/тему, если нет релиза, содержащего всё вышеперечисленное.
7. Добавить issue в трекере проблем Grav с подробной информацией о вашем плагине, и мы проведем его быстрый тест, чтобы убедиться, что он работает, а затем добавим его. Обратите внимание, что это не обязательно делать, если вы выпускаете новую версию плагина или темы, которая уже есть в репозитории. Она будет подхвачена автоматически.

Формат списка изменений⚓︎

Сайт GetGrav.org использует собственный формат журнала изменений, который написан с использованием стандартного Markdown, но с ним можно работать с помощью простого CSS и отображается в привлекательном формате. Чтобы гарантировать, что ваши журналы изменений могут быть проанализированы и отформатированы должным образом, используйте следующий синтаксис:

# vX.Y.Z
## 01/01/2015

1. [](#new)
    * Добавленная фича
    * Другая добавленная фича
2. [](#improved)
    * Сделанное улучшение
    * Другое сделанное улучшение
3. [](#bugfix)
     * Реализованное исправление
     * Другое реализованное исправление

...повторять сколько нужно раз...

Каждый раздел #new, #improved, #bugfix необязателен, просто включите нужные разделы.

Настройка GitHub⚓︎

Как и в наши дни, GitHub станет вашим лучшим другом, когда дело доходит до разработки для Grav. Мы создали несколько инструментов, чтобы максимально упростить это, но есть некоторые шаблоны разработки, которым вы должны следовать, чтобы упростить процесс.

Клонируйте все репозитории, с которыми вы планируете работать, в одну папку Projects или Development на вашем компьютере. Это позволит нашим инструментам находить нужные репозитории.

Grav также имеет некоторые зависимости (продиктованные файлом .dependencies), которые включают плагины Error и Problems, а также тему Antimatter. Вы можете следовать этим инструкциям, чтобы клонировать эти частички на свой компьютер.

cd
mkdir Projects
cd Projects
mkdir Grav
cd Grav
git clone https://github.com/getgrav/grav.git
git clone https://github.com/getgrav/grav-plugin-error.git
git clone https://github.com/getgrav/grav-plugin-problems.git
git clone https://github.com/getgrav/grav-theme-antimatter.git

Это клонирует все 4 репозитория в вашу папку ~/Projects/Grav.

Как правило, обычная процедура настройки тестового сайта для Grav заключается в использовании команды bin/grav new-project. Это верно для разработки, за исключением одного важного отличия. Поскольку мы хотим иметь возможность разрабатывать из вашего веб-корня, но чтобы в вашем клонированном коде отображались какие-либо изменения, нам необходимо символически связать соответствующие части. Мы делаем это, передавая флаг -s команде bin/grav new-project.

Требуется один дополнительный шаг. Вы должны указать команде, где она может найти ваши репозитории. Итак, выполните следующие действия, чтобы создать файл конфигурации в новой папке .grav/, которую вам нужно будет создать в корне вашего домашнего каталога:

cd
mkdir .grav
vi .grav/config

В этом файле: укажите, где расположены соответствующие файлы:

github_repos: /Users/your_user/Projects/Grav/

Убедитесь, что вы сохранили этот файл и что он доступен для чтения. Теперь вы можете создать свой символически связанный сайт, где ~/www - это ваш корневой веб-сайт, а ~/www/grav - это место, где будет создан ваш новый сайт для тестирования Grav:

cd ~/Projects/Grav/grav
bin/grav new-project -s ~/www/grav

Вы должны увидеть что-то вроде этого:

rhukster@gibblets:~/Projects/Grav/grav(develop○) » bin/grav new-project -s ~/www/grav

Creating Directories
    /cache
    /logs
    /images
    /assets
    /user/accounts
    /user/config
    /user/pages
    /user/data
    /user/plugins
    /user/themes

Resetting Symbolic Links
    /index.php -> /Users/rhuk/www/grav/index.php
    /composer.json -> /Users/rhuk/www/grav/composer.json
    /bin -> /Users/rhuk/www/grav/bin
    /system -> /Users/rhuk/www/grav/system

Pages Initializing
    /Users/rhuk/Projects/Grav/grav/user/pages -> Created

File Initializing
    /.dependencies -> Created
    /.htaccess -> Created
    /user/config/site.yaml -> Created
    /user/config/system.yaml -> Created

Permissions Initializing
    bin/grav permissions reset to 755

read local config from /Users/rhuk/.grav/config

Symlinking Bits
===============

SUCCESS symlinked grav-plugin-problems -> user/plugins/problems

SUCCESS symlinked grav-plugin-error -> user/plugins/error

SUCCESS symlinked grav-theme-antimatter -> user/themes/antimatter

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

Вы должны указать в своем браузере http://localhost/grav и увидеть только что созданный тестовый сайт. Теперь любые изменения, внесенные вами в папку ~/www/grav, будут готовы к фиксации и отправке в ваши клонированные репозитории.

Обслуживание заброшенных проектов⚓︎

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

1. Отправьте правильно сформированный протестированный запрос на перенос в исходный репозиторий.
2. Если сопровождающий не отвечает вообще по прошествии 30 дней, или если сопровождающий заявляет, что покидает ресурс и не желает предоставлять кому-либо доступ на запись, переходите к следующему шагу.
3. Отправьте новую issue в репозиторий Grav на GitHub со следующими данными:
   • Заголовок: [change-resource] Take over plugin/theme
   • Укажите название плагина и ссылку на исходный репозиторий.
   • Ссылка на ваш пул-реквест, оставшийся без ответа, или ссылку на беседу, в которой разработчик отказывается поддерживать свой ресурс.
4. Сопровождающие Grav рассмотрят дело и сообщат вам, одобрено ли поглощение. Если одобрение предоставлено, переходите к следующему шагу.
5. Подготовьте свой разветвленный репозиторий с новым релизом.
6. Добавьте в README примечание, что этот репозиторий является новым главным, и сделайте обратную ссылку на старый репозиторий.
7. Ответьте на issue, предоставив сопровождающим новый URL-адрес плагина.
8. Сопровождающие обновят GPM, и новые и обновленные установки теперь будут поступать из вашего разветвленного репозитория.