In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Структура директорий и файлов

From In-Portal Developers Guide

(Difference between revisions)
Jump to: navigation, search
(дополнение)
Current revision (18:04, 4 November 2009) (view source)
(дополнение)
 

Current revision


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

нет статей

Contents

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

  • 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) и тэгов, не связанных напрямую ни с одной из типичных секций модуля. Также в этой директории принято размещать переопределяемые для специфических нужд модуля классы.

Директория типичной секции

Содержит файл Unit Config для конфигурации соответствующего секции префикса. Первая часть имени файла Unit Config всегда совпадает с названием директории. Далее следует "_config.php". Например

<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 - скрипт, через который запускаются все шаблоны пользовательской части сайта.