From In-Portal Developers Guide

Current revision

This article is not finished yet! You see this message because current Article is finished yet or contains unverified information. How to write an Article.

[[:Category:|]]
Статьи в этой категории
нет статей

Директории верхнего уровня

• admin - содержит единственный файл index.php, через который запускаются шаблоны административной консоли.
• core - особый модуль, здесь находятся базовые шаблоны, скрипты и прочие файлы без которых система работать не может.
• директории типичных модулей - их названия начинаются на "in-" или на "proj-". Если на "in-" - значит это модуль in-portal. Если на "proj-" - значит это модуль платформы.
• system - каталог для файлов, динамически создаваемых и/или изменяемых системой. Этому каталогу требуются особые права доступа чтобы из PHP-скриптов можно было манипулировать находящимися в каталоге файлами. В каталоге содержатся скомпилированные в PHP-код шаблоны, загружаемые пользователями файлы, отчёты debugger и.т.п.
• themes - каталог для шаблонов, картинок, стилей и прочих файлов, используемых в пользовательской части сайта.

Описание типичного модуля

Многие директории в проекте - это директории модулей. Структура таких директорий практически одинакова.

Директория admin_templates

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

Секции

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

Если поддиректория директории admin_templates называется так же, как поддиректория директории units из другого модуля, то возможно там находятся подменяющие шаблоны. Это, как правило, можно уточнить посмотрев секцию ReplacementTemplates в файле units/sections/sections_config.php данного модуля.

Директории inc или incs

Здесь находятся шаблоны и связанные с ними файлы, например файлы стилей, которые используются в нескольких секциях.

Директория img

Содержит относящиеся к модулю графические файлы. Группы специфических файлов хранятся в нескольких поддиректориях:

• Директория icons cодержит
  • изображения секций для дерева главного меню административной консоли. Имена этих файлов начинаются с "icon24_", затем следует название секции. Формат файла - всегда ".gif". Например:
    • proj-base/admin_templates/img/icons/icon24_lang_management.gif - картинка для секции "lang_management" модуля proj-base.
  • изображения секций, имеющие место в левом верхнем углу шаблонов административной консоли. Имена этих файлов начинаются с "icon46_", затем следует название секции. Формат файла - всегда ".gif". Например:
    • proj-base/admin_templates/img/icons/icon46_users_management.gif - картинка для секции "users_management" модуля proj-base.
• Директория itemicons cодержит изображения для объектов в списке. В одном списке изображения могут быть разные в зависимости от статуса объекта. Например:
  • icon16_user.gif - для активных пользователей
  • icon16_user_disabled.gif - для заблокированных пользователей
  • icon16_user_pending.gif - для пользователей, ожидающих подтверждения
• Директория itemtabs cодержит изображения для закладок при добавлении/редактировании объекта.
• Директория toolbar cодержит изображения для кнопок в toolbar. Каждая кнопка может иметь три изображения - "включено", "mouseover" и "выключено". Имя файла всегда начинается с "tool_", затем следует уникальное имя кнопки, затем может следовать "_f2" для "mouseover" или "_f3" для "выключено". Например:
  • tool_primary_group.gif - кнопка primary_group, "включено"
  • tool_primary_group_f2.gif - кнопка primary_group, "mouseover"
  • tool_primary_group_f3.gif - кнопка primary_group, "выключено"

Типичные файлы в корне admin_templates

• catalog_tab.tpl - шаблон для отображения специфичных для модуля объектов в общем каталоге
• category_properties.tpl - шаблон для отображения специфичных для модуля полей на закладке Properties при редактировании категории
• export.tpl - шаблон параметров для экспорта данных модуля
• export_progress.tpl - шаблон прогресса (с AjaxProgressBar) для экспорта данных модуля
• export_finish.tpl - шаблон завершения экспорта данных модуля
• import.tpl - шаблон параметров для импорта данных модуля
• import_progress.tpl - шаблон прогресса (с AjaxProgressBar) для импорта данных модуля
• user_item_tab.tpl - шаблон для отображения привязанных к пользователю спtцифичных для модуля данных при добавленнии/редактировании пользователя, на закладке Items. Например, от модуля In-Commerce на этой закладке показывается список заказов данного пользователя.

Директория install

Файлы, используемвые системой при инсталляции, апгрейде и удалении модуля.

• english.lang - базовый набор специфичных для модуля фраз а также шаблоны для связанных с модулем системных e-mail. Всё - на английском языке.
• install_schema.sql - набор SQL-запросов, обеспечивающих необходимые изменения в структуре данных при инсталляции модуля.
• remove_schema.sql - набор SQL-запросов, обеспечивающих удаление специфичных для модуля таблиц (DROP TABLE).
• install_data.sql - набор SQL-запросов, обеспечивающих необходимые изменения в данных (INSERT, UPDATE, REPLACE, DELETE) при инсталляции модуля.
• upgrades.sql - набор SQL-запросов, выполненных после инсталляции модуля и меняющий структуру специфичных для модуля таблиц.
• install_order.txt - содержит число, определяющее порядок инсталляции модуля по отношению к другим модулям в случае когда несколько модулей инсталлируются одним запуском инстллятора.
• prerequisites.php - скрипт, для осуществления необходимых проверок перед инсталляцией или перед апгрейдом модуля. Например, этот скрипт может проверять наличие модулей и соответствие версий модулей.

Директория module_help

Файлы, содержащие HTML-код справки/помощи для определённого [[K4:Работа с опцией TitlePresets|TitlePreset]. Имена файлов совпадают с TitlePreset и имеют расшиение *.txt. Например

in-commerce/module_help/orders_processed.txt - справка, показываемая в pop-up окне при нажатии "?" в заголовке списка обработанных заказов.

Директория units

Может содержать множество типовых директорий для секций модуля, директорию helpers для нетипичных классов, используемых во многих местах системы, директорию sections с Unit Configs для главной секции модуля и типичных классов этой секции.

Директория sections

Главная директория модуля. Содержит sections_config.php<code> - главный Unit Configs модуля, содержащий описание главной секции модуля, родительской по отношению к остальным секциям модуля. Может содержать типичные классы обработчика событий и обработчика тэгов - для событий (как правило, связанных с другими событиями системы посредством технологии Hooks) и тэгов, не связанных напрямую ни с одной из типичных секций модуля. Также в этой директории принято размещать переопределяемые для специфических нужд модуля классы.

<code>in-commerce/units/products/products_config.php

Может содержать классы, обеспечивающие специфичную функциональность.

• обработчик событий - имя файла заканчивается на "_eh.php" или на "_event_handler.php". Например - in-auction/units/listing/listing_eh.php
• обработчик тэгов - имя файла заканчивается на "_tp.php" или на "_tag_processor.php". Например - in-auction/units/listing/listing_tp.php
• класс главного объекта префикса - имя файла заканчивается на "_item.php". Например in-auction/units/listing/listing_item.php
• класс главного списка префикса - имя файла заканчивается на "_list.php".

Директория helpers

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

Для регистрации этих вспомогательных классов в директории имеется файл с Unit Config - helpers_config.php. В отличие от директорий типичных секций, директория helpers не имеет своей секции в дереве главного меню административной консоли.

Файлы в корне модуля

• constants.php - файл с определением констант, необходимых для модуля.
• install.php - скрипт, выполняющий инсталляцию модуля.

Также в корне модуля могут располагаться скрипты для обмена данными с другими WEB-системами. Например in-auction/notify.php служит для получения eBay Platform Notifications с ebay.com

Особый модуль core

В отличие от остальных модулей, модуль core является обязательно присутствующей, неотъемлемой частью любого проекта на базе K4, поскольку этот модуль включает в себя всю базовую функциональность. Cтруктура директорий модуля core во многом совпадает с вышеописанной структурой типичного модуля.

Директория admin_templates

Как и в случае типичного модуля - содержит шаблоны. Но есть отличие в обращении к этим шаблонам - в пути к шаблону опускается первая часть - название модуля. То есть не core/users/users_list а просто users/users_list.

Особые шаблоны, не имеющие секции в дереве

• ajax/popup_manager.tpl - шаблон, к которому обращаются по технологии XMLHttpRequest с целью выяснить какого размера окно следует открывать для отображения открываемого в отдельном окне шаблона.
• browser - HTML-редактор на базе FCK-editor, соответствует префиксу fck (core/units/fck)
• emails - шаблоны для массовой рассылки e-mail. Задействуют префиксы emailevents (core/units/email_events) и emailmessages (core/units/email_messages).
• export - шаблоны для стандартного экспорта в CSV из списка административной консоли. Используется функциональность префикса adm (core/units/admin)
• import - шаблоны для стандартного импорта из CSV файла. Используется функциональность префикса adm (core/units/admin)
• popups - шаблоны стандартных pop-up окон, используемых во многих секциях.
  • column_picker - шаблон для выбора отображаемых полей и определения порядка столбцов в списках административной консоли
  • editor - простой, по сравнению с вышеназванным "browser", редактор для полей, содержащих HTML-код.
  • translator - шаблон для редактирования многоязычных полей. Используется функциональность префикса trans (core/units/translator)
• summary/root.tpl - шаблон для отображения информации общего характера - о количестве категорий, пользователей и.т.п. Включается в шаблон sections_list при отображении главной (root) секции дерева административной консоли в проектах с модулями In-Portal

Особенности директории img

Директория core/img включает в себя несколько особых директорий:

• browser - содержит файлы изображений для редактора на базе FCK-editor.
• summary - файлы изображений для шаблона summary/root.tpl
• tree - файлы изображений для отображения дерева главного меню административной консоли

Особенности директории incs

Директория core/incs - содержит блоки и стили, широко используемые в шаблонах административной консоли

• close_popup.tpl - шаблон, на который делается перенаправление с целью закрытия окна
• config_blocks.tpl - блоки для отображения и редактирования стандартных полей конфигурации
• grid_blocks.tpl - блоки для отображения списка
• form_blocks.tpl - блоки для отображения и редактирвания данных объекта
• menu_blocks.tpl - блоки для создания меню
• tab_blocks.tpl - блоки для отображения закладок
• nlsmenu.css - стили для меню
• sections_list.css - стили для шаблона sections_list.tpl
• style.css - основной файл стилей административной консоли

Директория js

Содержит широко используемые в административной консоли JavaScript функции и объекты.

• ajax.js содержит класс Request</code> для обеспечения базовой функциональности XMLHttpRequest</code> а также несколько наиболее часто используемых классов, основывающихся на этой технологии:
  • AjaxProgressBar - класс для отображения прогресса в длительных процессах - таких как отсылка большого количества e-mail, копирование, обработка, импорт или экспорт большого количесства данных.
  • AjaxPopupManager - класс для получения и сохранения (кеширования) размеров окон административной консоли.
  • AjaxDropdownPreloader - класс для создания динамических полей типа Dropdown, с опциями, автоматически меняющимися в зависимости от значений других полей формы.
• ajax_dropdown.js содержит класс для создания динамического Dropdown-подсказки вариантов к текстовому полю ввода, опции которого зависят от текущего содержимого текстового поля.
• calendar.js и директория calendar - скрипты для ввода поля типа "дата".
• catalog.js - класс для обеспечения функциональности централизованного каталога в административной консоли
• colorselector.js - класс для ввода поля типа "цвет".
• drag.js - базовый класс для построения функциональности с использованием перетаскивания объектов мышью.
• forms.js - вспомогательная функциональность стандартной формы ввода данных в административной консоли (контроль над размерами элементов ввода данных, отображение ошибок).
• grid.js, grid_scroller.js - классы для построения стандартного списка в административной консоли.
• is.js - скрипт для определения версии браузера
• nlsmenu.js - скрипт для создания динамических меню
• script.js - основной набор скриптов административной консоли
• swfobject.js - класс для определения версии flash-проигрывателя и корректной вставки flash-объектов на страницу.
• toolbar.js - класс для быстрого создания и обеспечения функциональности стандартного toolbar административной консоли
• tree.js - класс для отображения дерева главного меню административной консоли
• uploader.js и директория uploader - скрипты для загрузки на сервер файлов с помощью flash-объекта (файл core/admin_templates/swfupload.swf)

Директория editor

Базовые файлы HTML-редактора FCK-editor.

Директория install

В отличие от типичных модулей, дополнительно содержит шаблоны инсталлятора системы:

• директория step_templates - шаблоны, соответствующие этапам процесса инсталляции/обновления системы.
• директория incs - изображения, стили и JavaScript-файлы для инсталлятора.

Директория kernel

Содержит файлы, обеспечивающие базовую функциональность системы в целом.

• директория db - набор классов для работы с базой данных
• директория fonts - шрифты для генерирования изображений с текстом. В настоящее время там только один шрифт и он используется для генерирования изображений с буквенно-цифровым кодом во вспомогательном модуле core/units/general/helpers/captcha_helper.php
• директория languages содержит класс для кеширования фраз
• директория nparser содержит классы для предварительной компиляции шаблонов с целью более быстрого их выполнения
• директория parser содержит классы старой версии компилятора шаблонов, которая используется если nparser не включен
• директория processors содержит классы для обработки базовых тагов
• директория session содержит класс для управления пользовательскими и администраторскими сессиями
• директория utility содержит классы, обеспечивающие базовую функциональность
  • директория debugger - содержит скрипт для показа предварительно сгенерированного отчёта о выполнении отлаживаемого PHP-скрипта, а также слили и JavaScript, используемые при показе этого отчёта.
  • директория formatters содержит классы базовых форматтеров - скриптов для преобразования значений из базы данных в удобный для пользователей формат и обратно.
  • в корне директории utility находятся файлы:
    • adodb-time.inc.php - функции для работы с датами
    • cache.php - набор классов для кеширования данных
    • debugger.php - класс для отладки PHP-скриптов
    • email_send.php - класс для отсылки электронной почты
    • event.php - базовый класс системного события
    • factory.php - класс для централизованного создания объектов и хранения ссылок на них
    • filters.php - класс для создания фильтров к SQL-запросам
    • http_query.php - класс, обрабатывающий HTTP-запросы, анализирующий их и переводящих данные запросов в системный формат
    • multibyte.php - заглушка на случай если в текущей версии PHP отстутствуют функции для обработки строк в мультибайтной кодировке.
    • params.php - класс для работы с параметрами тэгов K4 - обеспечивает выделение параметров из тэга и их хранение.
    • socket.php - класс для операций с удалёнными портами (sockets)
    • temp_handler.php - класс для работы с временными таблицами
    • unit_config_reader.php - класс для считывания конфигурации, её хранения и обеспечения доступа к параметрам конфигурации

В корне директории kernel находятся файлы:

• application.php - центральный класс системы, обеспечивает создание базовых объектов и доступ к ним.
• constants.php - определение основных констант
• event_handler.php - базовый класс для обработчиков событий
• event_manager.php - класс для работы с периодически выполняемыми событиями (Regular Events).
• globals.php - глобально определённые функции вспомогательного характера
• kbase.php - несколько базовых класс классов
• startup.php - запускается в самом начале работы системы, подключает необходимфе файлы, выполняет ряд критических проверок, при отрицательном результате которых запуск системы может быть остановлен

В корне директории core находится файл install.php. В отличие от типичных модулей этот скрипт инсталлирует не один модуль, а предоставляет набор возможностей для установки/обновления системы в целом.

Особый модуль custom

Модуль custom предназначен для внесения изменений и дополнений, необходимых для одного данного конкретного проекта. Отсюда его особеность и отличие от типичных модулей. Если типичные модули проектируются так, чтобы они были максимально независимы, имели минимум связей с другими модулями, а при наличии связей делали проверку - установлен требуемый модуль или нет, то в модуле custom широко используется подмена шаблонов других модулей, переопределение классов других модулей и прочие межмодульные взаимодействия. Отсюда следует, что у модуля custom:

• в директории admin_templates могут находиться поддиректории с шаблонами подмены, соответствующими Unit Configs из других модулей. Например в custom/admin_templates/products/ могут находиться шаблоны подмены, соответствующие in-commerce/admin_templates/products/
• в директории units/sections/ могут находиться файлы с переопределёнными классами других модулей. Например в custom/units/sections/ может находиться файл e_users_eh.php, содержащий переопределение для класса из core/units/users/users_event.handler.php

Директория system

• backupdata - директория для размещения резервных копий базы данных, создаваемых с помошью сервиса Tools->Backup в главном меню административной консоли.
• cache - директория содержит
  • переведенные в PHP-код шаблоны. PHP-файлы называются так же, как и сооветствующие им шаблоны - лишь расширение изменено с .tpl на .php. Структурно эти PHP-файлы размещены относительно директории cache точно так же, как соответствующие им шаблоны относительно корневой директории сайта. Например шаблон административной консоли core/admin_templates/index.tpl переводится в PHP-файл system/cache/core/admin_templates/index.php. Аналогично шаблон пользовательской части сайта themes/theme_someproject/index.tpl переводится в PHP-файл system/cache/themes/theme_someproject/index.php.
  • файлы с результатами работы отладчика размещаются в корне каталога cache и имеют характерные имена, содержащие идентификатор сессии. Например, файл debug_@128077469@.txt содержит данные последнего отлаживаемого запроса, сделанного в сессии с идентификатором 128077469.
• downloads - эта директория предназначена для файлов, которые посетители сайта могут скачивать, находя ссылки на них в каталогах пользовательской части сайта. Хотя каталоги могут быть разного рода - продукты, новости и другие, для работы с такого рода файлами используется общая функциональность и общий каталог.
• export - директория для размещения файлов с результатами экспорта. Экспортируются данные списков в CSV-формате, содержимое каталога, данные языкового набора (фразы и шаблоны e-mail).
• images - директория для хранения изображений
  • emoticons - изображения эмоций (смайлики) - используются при общении в форуме модуля in-bulletin
  • manufacturers - логотипы фирм-производителей - используется при подключении модуля in-commerce
    • resized - кэш для хранения тех логотипов фирм-производителей с изменённым размером изображения
  • pending - директория для предварительной закачки изображений при вводе данных в административной консоли. Изображения здесь хранятся пока они загружены только для записи из временной таблицы. При копировании записей в live-таблицу, изображения переносятся из директории pending в директорию images
  • resized - кэш для хранения изображений с изменённым размером. При этом к имени файла дописываются символы, обозначающие до какого размера произошло изменение. Например, если оригинальный файл system/images/apple.gif был уменьшен до размера 120x147, то в директории system/images/resized/ будет файл apple_120x147.gif
• import - сюда помещаются файлы, закачиваемые на сервер с целью импорта данных. Импортироваться могут элементы каталога In-Portal - например продукты модуля in-commerce, ссылки модуля in-link.
• stylesheets - в этой директории хранятся скомпилированных CSS-файлы для пользовательской части сайта (используется только в In-Portal)
• tmp - директория для временного хранения файлов. Например, в процессе загрузки файла посредством flash-загрузчика.
• user_files - директория для хранения файлов, загружаемых в администраторской части сайта при вводе содержимого CMS-блоков
  • icons - в этой дирктории хранятся изображения-пиктограммы, обозначающие различные типы файлов. Их удобно использовать если в пользовательской части сайта надо отображать имена файлов - пиктограмма рядом с именем файла, соответствующая его типу, повышает интуитивность интерфейса.
  • images - директория по умолчанию для размещения изображений, закачиваемых на сервер посредством файл-менеджера редактора FCK

Директория themes

Содержит директории тем. Каждая тема представляет собой набор шаблонов и прочих файлов, обеспечивающих интерфейс пользовательской части сайта. Тем может быть несколько - с разными цветовыми решениями, даже с разной функциональностью. Файлы каждой темы находятся в отдельной директории. Администратор сайта в административной консоли может переключать темы, определяя которая из тем будет текущей.

Стандартная тема

На практие обычно используется только одна тема, размещаемая в директории с названием, состоящим из слова "theme", знака подчёркивания и названия модуля проекта в CVS. Например для проекта "resumark" получается название директории - "theme_resumark". Директория темы может содержать такие типичные поддиректории:

• designs - эта директория содержит шаблоны для создания виртуальных страниц
• img - в этой директории хранятся изображения, используемые в дизайне пользовательской части сайта
• inc - здесь могут храниться файлы стилей, JavaScript пользовательской части сайта, подключаемые шаблоны - такие как header.tpl и footer.tpl, файл styles.xml, задающий набор стандартных стилей текста для редактора FCK.
• директории с названиями, соответствующими названиям модулей (in-commerce, in-edit, in-bulletin) как правило содержат шаблоны и другие файлы, обеспечивающие функциональность соответствующих модулей на пользовательской части сайта.
  • директории с названиями designs, elements могут содержать шаблоны с блоками, используемыми в других шаблонах - например блок для отображения кнопки, блок для отображения подсекции в левом или правом столбце (sidebar).
  • директория img - изображения, связанные с функциональностью конкретного модуля. Например, в директории in-commerce/img/ могут быть изображения логотипов, соответствующих разным формам оплаты PayPal, Visa, MasterCard...)
• директория platform по структуре похожа на директорию шаблонов модуля. Можно считать что она соответствует модулю Core.

Типичные файлы в корне темы это шаблоны:

• index.tpl - шаблон страницы по умолчанию пользовательской части сайта
• error_notfound.tpl - шаблон для перенаправления в случае отсутствия запрашиваемой страницы
• no_permission.tpl - шаблон для перенаправления в случае попытки получить доступ к закрытым для доступа ресурсам
• phrases_edit.tpl - шаблон для удобства создания фраз пользовательской части сайта. При включённом режиме отладки отсутствующие фразы отображаются в виде ссылок на этот шаблон.

Файлы в корне проекта

• config.php - файл конфигурации проекта. Содержит логин и пароль для доступа к базе данных, информацию об используемой лицензии, список проинсталлированных модулей и их версии.
• debug.php - файл конфигурации отладчика. Может отсутствовать когда отладчик не нужен.
• index.php - скрипт, через который запускаются все шаблоны пользовательской части сайта.