Как разрабатывать Рецепты?

Программирование Рецепты в PmWiki — это дополнительные модули, расширяющие базовый функционал системы. На pmwiki.org есть официальный раздел Cookbook с большим количеством Рецептов. На pmwiki.ru также есть свои Cooks, где представлены русскоязычные Рецепты, разработанные в основном для Rext.

Рецепты могут быть как готовыми программными модулями с PHP-кодом, так и «концепциями решения задачи». Дело в том, что движок PmWiki такой гибкий, что многие задачи можно решить без использования «низкоуровнего» PHP-программирования, просто на базе самого движка и его вики-функций. Но для этого знать, как это сделать. Рецепты вполне могут быть просто описанием решения той или иной нестандартной задачи с помощью PmWiki.

Когда создавать Рецепт, а когда нет?

Вы решили с помощью него свою задачу, лучше, чем кто-то либо до вас, и хотите поделиться результатом.
Прежде чем разрабатывать что-либо, поищите готовое решение в Cookbook и Cooks, возможно, вам оно подойдёт. Большая часть Рецептов Open Soucre, так что, возможно, вы сможете доработать чужой Рецепт под свои нужны.

Рецепт должен решать узкоспециализированные задачи.
Например, если вы хотите сделать Рецепт, создающий в режиме редактирования необычную кликабельную Карту Сайта, подумайте, можно ли разбить его на два: для создания Карт Сайта и для кликабельности ссылок? Если можно, разбейте (см. следующий параграф).

Рецепт должен быть универсальным и совместим с ядром.
Если вы разработали что-то классное для своего сайта, чтобы сделать из этого Рецепт, необходимо обеспечить его совместимость с ядром PmWiki. Ваша разработка должна работать не только на вашем сайте, но и на чистом дистрибутиве PmWiki. Рецепт также должен удовлетворять Cookbook:ModuleGuidelines.

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

Вы должны знать PmWiki и выделить время на оформление.
Довольно очевидно, что для разработки модуля для любой системы, требуется знание этой системы. Иначе, скорее всего, вы что-нибудь сделаете не так.

Подавляющее большинство популярных задач в PmWiki можно решить комбинацией функций ядра и уже существующих Рецептов. Если вы не уверены, следует ли вам создавать Рецепт для вашей задачи, спросите нас.

Финальной целью разработки Рецепта является его публикация. Это не совсем простая задача, которая также потребует времени. Мы рекомендуем разрабатывать, документировать и оформлять Рецепты в официальном репозитории на английском языке. Однако, если вы разработали и готовы опубликовать Рецепт только на русском, вероятно вы можете сделать это на PmWiki.ru. Для этого напишите нам.

Хотя Рецепт должен решать общезначимые задачи…
…даже если вы разрабатываете что-то, что наверняка не понадобится больше никому, всё же ознакомьтесь с нижеследующими советами, чтобы реализовать запланированное более грамотно. Следование советам улучшит архитектуру и упростит использование разработки даже в рамках одного проекта.

Какие особенности программирования надо знать?

В первую очередь, ознакомьтесь с Cookbook:ModuleGuidelines. Предполагая, что вы это уже сделали, приведем дополнительные рекомендации из личного опыта.

Старайтесь ограничиться одним php-файлом в /cookbook
Расширяйте массивы $HTMLStylesFmt, $HTMLHeaderFmt, $HTMLFooterFmt для размещения незначительного количества JS и CSS кода, а также подключения CSS- и JS-файлов.

Привязывайте функционал Рецепта к новому действию ?action=* и авторизации PmWiki. Не допускайте обработку GET-параметров без них.
Иначе наверняка пострадает SEO (страницы действий вашего Рецепта проиндексируются поисковиками) и, вероятно, безопасность.

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

Определяйте конфигурационные переменные через функции SDV() и SDVA().
Это позволит переопределять их в любых местах конфигурации (в конфиге Сайта/Группы/Страницы, скине, дочерних вики-фермах), как до, так и после подключения Рецепта.

Придумайте хорошее «ключевое слово» для вашего рецепта и старайтесь использовать его везде
Положим, вы делаете рецепт «Мой рецепт». По-английски — MyCook. Будет отлично, если URL-адрес с описанием Рецепта, PHP, JS и CSS файлы рецепта, шаблон макета дизайна, выходные PHP- и JS-переменные, CSS-классы также будут называться MyCook или использовать MyCook в качестве префикса. Это снижает путаницу, ведь будет всегда понятно, к чему относятся перечисленные сущности.