Краткий экскурс в модификацию конференций phpBB

[url=http://www.phpbbguru.net/kb/modding/how-to-install-mod/]Как устанавливать МОДы[/url]

Что такое МОД

МОД - модификация вашей конференции phpBB, которая добавляет функциональность, изначально отсутствующую в стандарной комплектации phpBB (например, возможность поблагодарить автора поста) или расширяет имеющийся функционал (например, МОД Автогрупп - перенос пользователя из группы в группу в зависимости от определённых условий), или вносит косметические изменения в отображение конференции (например, расположение списка подфорумов в столбик).

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

Где искать МОДы
В интернете, конечно. Их достаточно много на оффсайте: http://www.phpbb.com, на некоторых известных модохранилищах: http://www.phpbbhacks.com, http://www.sourceforge.net и сайтах авторов МОДов. На нашей конференции в разделе МОДЫ вы также сможете найти некоторые из них. Учтите, что гарантированную поддержку вы можете ожидать только по МОДам, скачанным с базы данных МОДов оффсайта - http://www.phpbb.com/mods/db/.

Как установить МОД

1. Найти актуальную версию интересующего вас МОДа. Актуальную - значит наиболее позднюю по времени публикации. Обязательно загляните на сайт автора МОДа для проверки наличия новейших (более поздних) версий МОДа.
2. Скачать файл-архив с МОДом.
3. Разархивировать файл в отдельную папку. Мы рекомендуем делать это на вашем локальном компьютере. Так удобнее и быстрее. После распаковки архива вы должны увидеть папку, в которой по крайней мере 3 файла:
   
   • *.XML (например, install_mod.xml)
   • *.XSL (скорее всего modx.prosilver.en.xsl)
   • файл лицензии GPL (обычно license.txt)
   Также вы можете обнаружить:
   
   • папку /root, в которой находятся дополнительные кодовые файлы МОДа. Их нужно будет скопировать на вашу конференцию, соблюдая структуру вложенных паппок. Как правило, она повторяет структуру папок конференции phpBB.
   • папку /contrib, в которой находятся дополнения к МОДу (по сути - тоже МОДы), содержащие код, или файлы для совместимости или корректной работы устанавливаемого МОДа с другими МОДами, установленными на вашем форуме, а также файлы для обновления (upgrade) перехода с предыдущих версий данного МОДа, если вы уже ставили более раннюю версию этого МОДа. Устанавливать эти МОДы, по-другому их называют адд-оны (add-ons), не всегда обязательно (если иное не указано в инструкции).
4. Внимательно прочтите инструкцию.

Саму инструкцию по установке содержит файл *.XML (eXtensible Markup Language, например, install_mod.xml), но его синтаксис, как правило, не предназначен для человеческого чтения. Однако, XSL (eXtensible Stylesheet Language), помогает сделать XML файл таким, чтобы при просмотре XML-файла в браузере, он выглядел как обычные веб-страницы. Практически все браузеры поддерживают язык XML. Поэтому, для того чтобы прочитать файл, просто дважды щелкните мышкой на его названии и он должен автоматически загрузиться в ваш веб-браузер.

Не забывайте, что открывать файл вы должны в той же папке, в которую разархивировали МОД. Это необходимо для того, чтобы XML-файл нашёл и загрузил таблицу стилей (XSL-файл). Иначе браузер просто выдаст ошибку.

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



В верхнем правом углу есть меню выбора языка, что позволяет изменить язык файла. Не стесняйтесь пользоваться этой возможностью, она намного облегчит вам понимание инструкции. Надеемся, что вы выберете русский язык   В настоящее время есть более 20 языков, доступных для использования. По умолчанию инструкции пишутся с использованием английского интерфейса. Если Вы изменяете язык интерфейса, может быть вам потребуется разрешить JavaScript. Если Ваш браузер не поддерживает этот вариант, и вы не можете изменить язык интерфейса MODX, попробуйте открыть файл с помощью других браузеров, например IE или Firefox.

Инструкция состоит их 2 основных разделов, общая информация о МОДе и фактическое руководство: перечень того, что вы должны сделать, чтобы установить МОД на своем форуме phpBB.

В первом разделе вы увидите:

• About this MOD - О моде
  Название МОДа, описание, версию, оценку сложности и времени для завершения установки, а также Примечания автора. Авторы иногда считают необходимым включить дополнительную информацию об их МОДах. Это всегда полезно прочитать перед установкой.
• Author - Автор
  Здесь вы увидите автора(ов) этого МОДА. Его/ее адрес электронной почты, личные веб-страницы и реальное имя.
• Files to Edit - Файлы для изменения
  Список файлов, которые вам придется редактировать. Указанные имена файлов включают полный путь до файла(ов). Таким образом, вы будете знать, где найти конкретный файл(ы) для редактирования.
• Included Files - Дополнительные файлы
  Список дополнительных файлов с указанием полного пути, которые нужно будет скопировать (добавить) к файлам конференции.
• Additional MODX Files - Дополнительные инструкции
  Дополнительные инструкции, например, для не английских языковых пакетов, для дополнительных стилей, для обновления версий МОДа.
• Disclaimer & Other Notes - Уведомления и Прочие замечания
  Уведомление о версии phpBB, с которой совместим МОД, напоминание о необходимости проверить наличие актуальной версии МОДа, а также о том, что вам необходимо сделать резервную копию ваших файлов, прежде чем делать любые изменения в коде phpBB. Вы должны также создать резервные копии базы данных (или связанных таблиц), если МОД требует изменений в вашей базе данных. В случае возникновения каких-либо ошибок при установке, вы можете восстановить резервные файлы/базу данных. Не забывайте делать это!
• License & English Support - Лицензия и Англоязычная поддержка
  Большинство МОДов сделаны под GPL лицензией. Если у вас есть сомнения по поводу этого, обратитесь к автору. Поддержку на русском языке вы можете найти на нашей конференции в разделе Модификация phpBB 3.0.x
• MOD History - История МОДа: Вы можете проследить историю развития МОДа, прочитав этот раздел инструкции.

(Описание частей Инструкции приводится с учётом версии MODX 1.2.3 В более ранних версиях их расположение незначительно отличается. Например, в версии MODX 1.2.2 Примечания автора располагались перед Историей МОДа, а сведения о Лицензии - после Истории МОДа).

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

• SQL
  В этой секции описываются необходимые изменения, которые вам следует внести в вашу базу данных. Действия описываются как запросы SQL к базе данных, которые необходимо выполнить при установке МОДа. Например, запрос на добавление поля в таблицу пользователей:

  ALTER TABLE phpbb_users ADD user_allow_thanks_pm tinyint(1) UNSIGNED DEFAULT '0' NOT NULL;

  В запросах указывается префикс имён таблиц, принятый по умолчанию: phpbb_. Если Вы при установке конференции указали префикс, отличный от используемого по умолчанию, вы должны заменить этот префикс на свой. Например:  

  ALTER TABLE myprefix_users ADD user_allow_thanks_pm tinyint(1) UNSIGNED DEFAULT '0' NOT NULL;

  Для выполнения SQL-запросов Вы можете воспользоваться любым менеджером работы с БД (например, phpMyAdmin). Как правило, этот менеджер имеется в панели управления сайта. Для выполнения запроса нужно выбрать вашу базу данных, скопировать запрос в окно SQL менеджера и нажать кнопку Выполнить (или Пошёл).
  
  
  
  
• Часто в архиве с модом идет php-файл (например, db_update.php), который сам внесет необходимые изменения в БД. В инструкции, как правило, специально оговаривается этот момент. Обычно указанный файл необходимо поместить в корневой каталог вашего форума (или в специально указанную папку) и обратиться к нему через браузер - то есть набрать в адресной строке браузера
  http://адрес_вашей_конференции/имя_файла
  При этом часто требуется, чтобы вы были залогинены на конференции в качестве администратора.

• File Copy - Копирование файлов
  В этой секции указывается полный список файлов, которые необходимо скопировать (добавить) к вашим файлам конференции. Файлы указаны с полным путем. Как правило, в архиве МОДа эти файлы помещены в папку /root, которая соответствует корневой папке вашей конференции. Не забывайте соблюдать структуру вложенных папок при копировании файлов.
• Edits - Редактирование.
  В этой секции последовательно указаны все действия по редактированию кода файлов вашей конференции. Учтите, что использовать следует простой текстовый редактор (который не добавляет отсебятины). Со списком рекомендуемых текстовых редакторов можно ознакомиться здесь. Кроме того, важно сохранение файлов в кодировке UTF-8 без BOM.
  
  Теперь рассмотрим команды редактирования:
  
  • Open - Открыть
    Это команда предлагает вам открыть в текстовом редакторе файл, в который необходимо внести изменения.
  • Find - Найти
    Это команда предлагает вам найти указанную последовательность символов (фрагмент кода) в открытом для редактирования файле. Поиск следует начинать с начала файла - с первого символа первой строки кода. Учтите, что для поиска может быть указана не вся строка, а только её часть (начало строки, середина, окончание строки). В заданном для поиска фрагменте кода важны все символы, в том числе и пробелы, и символы табуляции. Если два или более действий [FIND] следует один за другим, то их так и следует выполнять: каждое последующее действие с того места в файле, на котором вы остановились после выполнения первого. Так иногда бывает в инструкции для облегчения поиска. Например, нужно отредактировать одну конкретную строку, которая встречается в файле несколько раз. Тогда для поиска указывается какой-либо уникальный фрагмент, находящийся чуть выше искомой строки. И следующее действие [FIND] укажет вам уже именно нужную строку.
  • Add after - Добавить после
    Эта команда предлагает вам добавить указанный фрагмент кода после найденного. Учтите, что добавлять нужно именно после найденного (с новой строки), а не в найденную строку кода.
  • Add before - Добавить перед
    Эта команда предлагает вам добавит указанный фрагмент кода перед найденной строкой кода. Учтите, что добавлять нужно именно перед найденной строкой, а не в найденную строку.
  • Replace With - Заменить
    Эта команда предлагает вам указанным фрагментом кода найденный ранее фрагмент.
  • Increment - Изменить
    Эта команда предлагает изменить (увеличить или уменьшить) численное значение указанных переменных в найденном фрагменте кода.
  • Строковые команды:
    In-line Find - Найти
    In-line Add after - Добавить после
    In-line Add before - Добавить перед
    In-line Replace With - Заменить
    In-line Increment - Изменить
    Эти команды аналогичны выше перечисленным, но выполнять их нужно с фрагментами внутри одной строки кода.
    
    Например, результатом данной инструкции:

    == Find ==
            $user->add_lang('bbcode', false, true);
    == Add after ==
        break;

    будет следующий код:

            $user->add_lang('bbcode', false, true);
        break;

    А результатом такой инструкции:

    == Find ==
            $user->add_lang('bbcode', false, true);
    == In-line Find ==
    true
    == In-line Replace ==
    false

    будет следующий код:

            $user->add_lang('bbcode', false, false);

• DIY Instructions - Сделай сам
  В этой секции приводятся заключительные инструкции для установки МОДа, которые, как правило, не могут быть выполнены автоматически (например, установочным скриптом). Вам следует их выполнить, в точности следуя указаниям. Это может быть указания на создания модуля в административном разделе, очистке кеша, обновлении набора изображений, расстановке прав доступа и т.п.

Вот, собственно, и всё! 

Заключение

• Выбор МОДов.
  Если в названии МОДа имеется префикс, то вам следует быть внимательными. Обычно используюся следующие префиксы:
  
  • [ABD] - abandoned означает, что разработка и поддержка МОДа заброшена (прекращена) автором.
  • [DEV] - developed означает, что данный МОД находится в стадии разработки. Фактически, это ещё не полноценный МОД, а только наброски, идеи.
  • [ALPHA] - означает, что МОД находится в начальной стадии разработки. Он уже доступен для скачивания, но поддержка может не оказываться.
  • [BETA] - beta означает, что МОД находится в тестовой стадии и может быть использован опытными пользователями для тестирования. Не рекомендуется ставить на живые конференции бета-версии МОДов!
  • [RC] - release candidate означает, что МОД практически закончен и ждёт финальной валидации.
  • [MODDB] - означает, что МОД прошёл валидацию и включён в базу данных МОДов на официальном сайте phpBB.com
• Инструкция.
  Если вы не нашли в инструкции по установке МОДа какой-либо из выше перечисленных секций, это означает, что для данного МОДа она не является необходимой. Например, если нет секции SQL, то вам не нужно вносить изменения в базу данных, если нет секции File copy - то нет дополнительных файлов, которые следует скопировать, и т.д.
• База данных.
  Если вы испытываете затрудения с выполнением SQL-запросов к базе данных (например, у вас нет доступа к какому-нибудь менеджеру работы с базой данных), то вы можете попробовать самостоятельно сгенерировать установочный файл, который выполнит необходимые изменения в базе данных. Для этого можно воспользоваться генератором, который можно найти, например, здесь - http://phpbbtools.ru/db_update_gen.php Вставьте SQL-запросы из инструкции в окно генератора (если запросов несколько, то вставьте их все, расположив каждый запрос с новой строки), нажмите Сгенерировать и скачайте получившейся файл. Этот файл вам следует поместить в корневую папку вашей конференции (туда, где находится файл config.php) и запустить через браузер (набрать в адресной строке http://адрес_вашей_конференции/имя_файла). После выполнения файла его следует удалить! В интернете есть несколько подобных генераторов, не забывайте только, что генераторы для phpBB2 и phpBB3 отличаются, будьте внимательны.
• Редактирование.
  Мы рекомендуем скачивать файлы с сервера, редактировать их на вашем локальном компьютере и закачивать обратно. Редактирование через FTP-клиента очень часто служит дополнительным источником ошибок и к тому же использует больше траффика.
  В процессе редактирования файлов кода вы последовательно выполняете различные действия. Учтите, что инструкция написана таким образом, что все действия в ней располагаются последовательно - от начала файла к его концу. То есть каждую следующую команду (например, FIND) следует выполнять из того места в редакторе, где вы оказались после выполнения предыдущей команды.
• Стили.
  Инструкции пишутся на стандартные стили (prosilver для phpBB3). Как правило, в папке /contrib имеется дополнительная инструкция для стиля subsilver2. Поэтому, если вы используете другие стили, то следует отредактировать и соответствующие файлы данных стилей, ориентируясь по инструкциям и здравому смыслу. Это не очень сложно, так как большинство стилей основано или на prosilver, или на subsilver2.
• Языки.
  Тоже самое относится и к языковым файлам (lang-файлам). Инструкции, как правило, написаны для английского языка, следовательно вам потребуется редактирование аналогичных файлов используемого вами языка (скорее всего, русского). Необходимые инструкции вы скорее всего сможете найти в разделе Локализация МОДов на нашей конференции.
• AutoMOD
  Это тоже МОД, предназначенный для быстрой установки других МОДов на вашу конференцию. Он может весьма значительно облегчить вам жизнь, особенно, если вы не слишком хотите вникать в тонкости редактирования исходного кода. Найти его можно здесь - phpbb.com/mods/automod/ В настоящее время AutoMOD умеет самостоятельно изменять код файлов, делая резервные копии для отмены, подсказывать вам об обнаружившихся несоответствиях. Следует заметить, что все МОДы, прошедшие официальную валидацию на сайте phpBB, написаны с учётом возможности установки с помощью AutoMOD. 
• И самое главное.
  И не забывайте, что перед началом установки МОДа необходимо сделать резервную копию ваших файлов, прежде чем делать любые изменения в коде phpBB. Вы должны также создать резервные копии базы данных (или связанных таблиц), если МОД требует изменений в вашей базе данных!