Принятые обозначения

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

Имена файлов

Корневые скрипты и HTML-шаблоны — нижний регистр, слова разделяются знаком подчёркивания:

index.php
page_catalog.php
main.htm
page_404.htm
item_product.htm

Модульные скрипты строятся по схеме из трёх частей, разделённых подчёркиванием:

{компания}_{группа}_{назначение}.php

• Компания — имя вашей компании или аббревиатура. В модулях, поставляемых с платформой, используется melbis. Для своих проектов выбирайте уникальный идентификатор: он отделит ваши модули от штатных и от чужих, если вы подключите готовые наработки.
• Группа — логическая группа, к которой относится модуль. Группирует связанные модули и помогает ориентироваться в большом проекте.
• Назначение — одно или несколько слов, поясняющих задачу модуля.

Примеры:

melbis_base_page.php       — базовый роутер страниц
melbis_store_card.php      — карточка товара
melbis_cataloge.php        — каталог
melbis_inc_logic.php       — библиотека бизнес-логики
melbis_block_slider.php    — слайдер
melbis_client_auth.php     — авторизация клиента

У библиотек частей четыре: слово inc занимает место группы, а собственная группа библиотеки переезжает в следующую часть имени — об этом ниже, в разделе «Группы модулей».

Кроме самого кода у каждого модуля есть параметры — кеш, входные данные, список таблиц, подключённые библиотеки. Они задаются в окне «Среда разработки», в правой панели рядом с редактором кода, и хранятся вместе с модулем. Подробнее это описано в разделе «Модульные скрипты».

Группы модулей

Группа в имени модуля несёт смысловую нагрузку и определяет отображение в дереве «Среды разработки». Зарезервирована только одна группа — inc (допускается также include или пустое значение). Модули с такой группой являются библиотеками: у них не может быть HTML-шаблонов, и парсер их не вызывает напрямую — их функции используются другими модулями.

Все остальные имена групп (base, store, cataloge, basket, client, block, cron и любые другие) вы определяете самостоятельно исходя из архитектуры проекта. Группа — это просто способ организовать модули в дереве файлов.

melbis_base_page.php       — обычный модуль (группа base)
melbis_store_card.php      — обычный модуль (группа store)
melbis_block_slider.php    — обычный модуль (группа block)

Группы библиотек

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

{компания}_inc_{группа}_{назначение}.php

В дереве «Среды разработки» библиотеки раскладываются по этой группе — рядом с обычными модулями и на том же уровне, но со своим значком. Общей папки inc, куда сваливались бы все библиотеки проекта, больше нет:

melbis
    auth          melbis_inc_auth.php
    logic         melbis_inc_logic.php
    web           melbis_inc_web_callback.php
                  melbis_inc_web_topic.php
    base          melbis_base_footer.php
                  melbis_base_head.php
                  melbis_base_header.php
                  melbis_base_page.php
    basket        melbis_basket.php
    cataloge      melbis_cataloge.php
                  melbis_cataloge_sub.php

Назначение можно опустить, если библиотека в группе одна: melbis_inc_logic.php — это группа logic без назначения, а melbis_inc_web_callback.php — группа web, назначение callback.

Смысл в том, чтобы библиотека лежала рядом с модулями, которые ею пользуются: melbis_inc_web_callback и melbis_inc_web_topic относятся к веб-части проекта и собраны в группу web, а не растворены среди всех прочих библиотек.

Функции в модульных скриптах

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

// Файл: melbis_store_card.php
function MELBIS_STORE_CARD($mVars)
{
    ...
}

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

Вспомогательные функции внутри того же модуля именуются с префиксом главной функции:

function MELBIS_STORE_CARD_price($mTpl, $mId)
{
    ...
}

function MELBIS_STORE_CARD_features($mTpl, $mId)
{
    ...
}

Такой подход гарантирует уникальность имён функций в глобальном пространстве имён PHP и позволяет сразу понять, к какому модулю относится та или иная функция.

Функции в библиотечных модулях (inc) именуются по той же схеме — с префиксом имени библиотеки:

// Файл: melbis_inc_logic.php
function MELBIS_INC_LOGIC_order_create(...)  { ... }
function MELBIS_INC_LOGIC_order_calc(...)    { ... }
function MELBIS_INC_LOGIC_order_edit(...)    { ... }

Переменные в PHP-скриптах

В главной функции модуля массив входных параметров принято называть $mVars.

Ключи в HTML-шаблонах

Все ключи шаблонизатора пишутся в верхнем регистре, слова разделяются знаком подчёркивания:

{TITLE}
{PAGE_NAME}
{PRODUCT:PRICE_OLD}
{#ITEMS}
    <a href="?id={ID}">{NAME|html}</a>
{ITEMS#}